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 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 Extensions

The table below lists the supported extensions and their levels:

Extension	Level	Description
x-adc-name	Root	Set the service name.
	Operation	Set the specific route name.
x-adc-labels	Root	Add labels to the service, route, or method as specified by the level. Value can be a string or a string array for multiple labels.
	Path
	Operation
x-adc-plugins	Root	Add plugins globally to a service. Value is an object containing one or more plugins.
	Path	Add plugins to a route or a method as specified by the level. Adding plugins at the operation level will split the routes, one including the plugin and the other without.
	Operation
x-adc-plugin-[plugin-name]	Root	Similar to x-adc-plugins but for a single plugin. These plugins will override the plugins with the same name configured in x-adc-plugins.
	Path
	Operation
x-adc-service-defaults	Root	Set the service parameters on a service, route, or method as specified by the level.
	Path
	Operation
x-adc-upstream-defaults	Root	Set the upstream parameters on a service, route, or method as specified by the level.
	Path
	Operation
x-adc-upstream-node-defaults	Root - Server	Set the node parameters of the upstream on a service, route, or method as specified by the level.
	Path - Server
	Operation - Server
x-adc-route-defaults	Root	Set the route parameters on a service, route, or method as specified by the level.
	Path
	Operation

Example Specification

The example specification below shows how to use the extensions:

openapi: 3.1.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