Skip to content

README.md

Latest commit

 

History

History
302 lines (263 loc) · 6.75 KB

README.md

File metadata and controls

302 lines (263 loc) · 6.75 KB
Raw

OpenAPI Converter

A library for implementing the OpenAPI specification and ADC profile conversion.

Direction Supported
OpenAPI to ADC ✅
ADC to OpenAPI ❎

Supported Extension Fields

Supported Levels
Root Level: on the root of the OAS document
Path Level: on each path object
Operation Level: on each HTTP method object for each path
Server Level: on each item in the servers field, supports Root, Path and Operation levels
Field Level Description
x-adc-name Root Level Override the name of the generated main service
Operation Level Override the name of the generated route
x-adc-labels Root Level Add labels field to the specified level. It supports string and string array formats.
Operation Level
x-adc-plugins Root Level Add plugins field to the specified level. It is an object that contains one or more plugins. Plugins set at the path or operation level are attached directly to the routes generated from that path or operation; they do not by themselves cause the service to be split.
Path Level
Operation Level
x-adc-plugin-[plugin-name] Root Level It will be consistent with x-adc-plugins. However, those configured using this format will override plugins of the same name in x-adc-plugins.
Path Level
Operation Level
x-adc-service-defaults Root Level It supports setting/overriding parameters in the service at various levels. This field on sub-levels will cause the service to be split.
Path Level
Operation Level
x-adc-upstream-defaults Root Level It supports setting/overriding parameters in the upstream at various levels. This field on sub-levels will cause the service to be split.
Path Level
Operation Level
x-adc-upstream-node-defaults Root Level - Server Level It supports setting/overriding parameters in the upstream's node at various levels. The servers field on sub-levels will cause the service to be split.
servers:
  - url: "https://httpbin.org"
    x-adc-upstream-node-defaults:
      priority: 100
  - url: "http://httpbin.org"
    x-adc-upstream-node-defaults:
      priority: 100
Path Level - Server Level
Operation Level - Server Level
x-adc-route-defaults Root Level It supports setting/overriding parameters in the route at various levels. Sub-level values override root-level values (operation > path > root); the merged result is applied to each route. This field does not by itself cause the service to be split.
Path Level
Operation Level

Extension Fields processing logic

x-adc-plugins and x-adc-plugin-[plugin-name]

They can be set at all three main levels, root, path, and operation.

Set both x-adc-plugins and x-adc-plugin-[plugin-name] at the same level

  1. For plugins with non-same names, their configurations will be merged.
Input Output 
x-adc-plugins:
  test-plugin1:
    key: value
x-adc-plugin-test-plugin2:
  key: value
 
plugins:
  test-plugin1:
    key: value
  test-plugin2:
    key: value
  1. For plugins with same names, the configurations in x-adc-plugin-[plugin-name] will override the one in x-adc-plugins.
Input Output 
x-adc-plugins:
  test-plugin1:
    key: value
x-adc-plugin-test-plugin1:
  key1: value1
 
plugins:
  test-plugin1:
    key1: value1

Set both x-adc-plugins or x-adc-plugin-[plugin-name] in multiple levels

  • Plugin configurations at the root level will be mapped to the exported service.

  • Both the path level and the operation level will be mapped to the routes included in this service.

The difference is:

  • The plugins on the path level will be included on all the routes corresponding to the method for that path.
Input Output 
...
paths:
  /anything:
    x-adc-plugin-test-plugin:
      key: value
    get: ...
    post: ...
 
...
services:
  - name: demo
    routes:
      - name: demo_anything_get
        uris: [/anything]
        methods: [GET]
        plugins:
          test-plugin:
            key: value
      - name: demo_anything_post
        uris: [/anything]
        methods: [POST]
        plugins:
          test-plugin:
            key: value
  • The plugin with the same name at the operation level as at the path level will override the one at the path.
Input Output 
...
paths:
  /anything:
    x-adc-plugin-test-plugin:
      key: value
    get: ...
      x-adc-plugin-test-plugin:
        key1: value1
      x-adc-plugin-test-plugin2:
        key: value
    post: ...
 
...
services:
  - name: demo
    routes:
      - name: demo_anything_get
        uris: [/anything]
        methods: [GET]
        plugins:
          test-plugin:
            key1: value1
          test-plugin2:
            key: value
      - name: demo_anything_post
        uris: [/anything]
        methods: [POST]
        plugins:
          test-plugin:
            key: value