Skip to main content

Version: 3.3.x

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:

ExtensionLevelDescription
x-adc-nameRootSet the service name.
OperationSet the specific route name.
x-adc-labelsRootAdd 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-pluginsRootAdd plugins globally to a service. Value is an object containing one or more plugins.
PathAdd 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]RootSimilar 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-defaultsRootSet the service parameters on a service, route, or method as specified by the level.
Path
Operation
x-adc-upstream-defaultsRootSet the upstream parameters on a service, route, or method as specified by the level.
Path
Operation
x-adc-upstream-node-defaultsRoot - ServerSet the node parameters of the upstream on a service, route, or method as specified by the level.
Path - Server
Operation - Server
x-adc-route-defaultsRootSet 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
API7.ai Logo

The digital world is connected by APIs,
API7.ai exists to make APIs more efficient, reliable, and secure.

Sign up for API7 newsletter

Product

API7 Gateway

SOC2 Type IIISO 27001HIPAAGDPRRed Herring

Copyright © APISEVEN PTE. LTD 2019 – 2025. Apache, Apache APISIX, APISIX, and associated open source project names are trademarks of the Apache Software Foundation