OpenAPI Converter Reference

ADC can convert OpenAPI v3.0 specifications to ADC configuration with the adc convert openapi command. This document provides a reference for the supported extensions/custom properties to configure API7 Enterprise-specific features like routes, plugins, and labels.

ADC OpenAPI extensions are supported at the following levels of a specification:

• Root level: The root level of the API specification. Properties at the root level are applied to the entire service.
• Path level: Path sections in the specification. Properties at the path level are applied to the specific route.
• Operation level: Each HTTP method in a path section. Properties at the operation level are applied to the specific HTTP method of the route.
• Server level: Server sections in the root, path, or operation level. Properties at the server level are applied to upstreams.

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.
	Path Level
	Operation Level
x-adc-plugins	Root Level	Add plugins field to the specified level. It is an object that contains one or more plugins.
	Path Level	Plugin objects at the Path level and Operation level will cause the service to be split, i.e. the sub-level containing the plugin will be included in a new service.
	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. This field on sub-levels will 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 different 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 the 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

Example Specification

The example specification below shows how to use the extensions:

openapi: 3.0.0
info:
  title: httpbin API
  description: httpbin API for the API7 Enterprise Getting Started guides.
  version: 1.0.0
servers:
  - url: 'http://httpbin.org:80'
x-adc-labels:
  server: production
  api: httpbin
x-adc-plugins:
  key-auth:
    _meta:
      disable: false
paths:
  /anything/*:
    get:
      summary: Returns anything that is passed into the request.
      x-adc-name: httpbin-anything
      x-adc-service-defaults:
        path_prefix: /api
      x-adc-upstream-defaults:
        timeout:
          connect: 10
          send: 10
          read: 10
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: string