Skip to main content

Version: 3.2.16.3

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

API Management for Modern Architectures with Edge, API Gateway, Kubernetes, and Service Mesh.

Product

API7 Cloud

SOC2 Type IIISO 27001HIPAAGDPRRed Herring

Copyright © APISEVEN Ltd. 2019 – 2024. Apache, Apache APISIX, APISIX, and associated open source project names are trademarks of the

Apache Software Foundation