Skip to main content
Version: 2.7.1

Import OpenAPI Guide

Overview#

The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection.

Apache APISIX Dashboard supports importing OpenApi3.0(we will use OAS3.0 for short) files, both json and yaml are supported, to create one or more Routes. Currently we support most of the OpenApi specifications, but there are some differences, which are in terms of compatibility and extended fields.

Extended fields#

There are some fields required in APISIX Route but are not included in the properties of OAS3.0, in order to provide convenience for extending custom route entities based on OAS3.0, we added some extended fields such as upstream, plugins, hosts and so on. All extensions start with x-apisix.

Extended fieldsAPISIX Route Properties
x-apisix-pluginsplugins
x-apisix-scriptscript
x-apisix-upstreamupstream
x-apisix-hosthost
x-apisix-hostshosts
x-apisix-remote_addrremote_addr
x-apisix-prioritypriority
x-apisix-varsvars
x-apisix-filter_funcfilter_func
x-apisix-labelslabels
x-apisix-enable_websocketenable_websocket
x-apisix-statusstatus
x-apisix-service_idservice_id
x-apisix-upstream_idupstream_id

Please pay attention that we only extended the first level of the field, and the sub level fields will still keep the same. Just take x-apisix-upstream for an example.

...# we add x-apisix-upstream as an extended field in OAS3.0 to stand for upstreamx-apisix-upstream:  # the sub fields of x-apisix-upstream still keeps the same as upstream's sub fields  type: roundrobin  nodes:    - host: 172.16.238.20      port: 1980      weight: 1...

See reference for more details of the APISIX Route Properties

OAS3.0 Compatibility#

When we import routes from OAS3.0, some fields in OAS3.0 will be missed because there are not corresponding fields in APISIX's Route:

  1. API General Info: used to describe the general information about your API, some times, a OAS3.0 file contains a series of apis which belong to a app, so this info is different from the api's name and extra basic info.

Example:

# this part of information will be missedopenapi: 3.0.0info:  version: 1.0.0-oas3  description: test desc  license:    name: Apache License 2.0    url: 'http://www.apache.org/licenses/LICENSE-2.0'  title: test title...
  1. API server and base path: upsream url + url prefix(options).

Example:

# this part of information will be missed...servers:  - url: https://api.example.com/v1...
  1. Path params: api params described in path.

Example:

# no matter how many path parameters in the uri# we will got the route with uri like `/get/*` after import route from OAS3.0 file...paths:  /get/{id}/{name}:    delete:      operationId: api1DELETE...
  1. Query params: api params described in query.

Example:

...paths:  /users:    get:      summary: Get a user by ID      # this part of information will be missed      parameters:        - in: path          name: userId          schema:            type: integer          required: true          description: Numeric ID of the user to get...
  1. Responses description and links: Define the responses for a API operations.

Example:

...paths:  /hello:    get:      description: hello world.      operationId: hello      x-apisix-service_id: service1      # this part of information will be missed      responses:        '200':          description: list response        default:          description: unexpected error...

Examples about how to Configure the OAS3.0 in different user scenarios#

Configure a basic published route#

notice: the default status of the imported route will be unpublished, which means the route can not be accessed, if you want to import a published route, you should add x-apisix-status: 1 in you OAS3.0 file

openapi: 3.0.0info:  version: 1.0.0-oas3  description: test desc  license:    name: Apache License 2.0    url: 'http://www.apache.org/licenses/LICENSE-2.0'  title: test titlepaths:  /hello: # route uri    get: # route method      description: hello world. # route desc      operationId: hello # route name      x-apisix-upstream: # route upstream        type: roundrobin        nodes:          - host: 172.16.238.20            port: 1980            weight: 1      x-apisix-status: 1 # the route will be published after imported      responses:        '200':          description: list response        default:          description: unexpected error

configure a route with plugins#

notice: most plugins supported by extended field x-apisix-plugins

openapi: 3.0.0info:  version: 1.0.0-oas3  description: test desc  license:    name: Apache License 2.0    url: 'http://www.apache.org/licenses/LICENSE-2.0'  title: test titlepaths:  /hello:    get:      description: hello world.      operationId: hello      x-apisix-upstream:        type: roundrobin        nodes:          - host: 172.16.238.20            port: 1980            weight: 1      x-apisix-plugins:        limit-count:          count: 2          time_window: 60          rejected_code: 503          key: remote_addr      responses:        '200':          description: list response        default:          description: unexpected error

configure a route with parameters validation#

notice: for plugin request-validation, we will use Parameter Serialization for header parameters validation and Describing Request Body for body parameters validation in OAS3.0

openapi: 3.0.0info:  version: "1"  description: |-    test desc  license:    name: Apache License 2.0    url: http://www.apache.org/licenses/LICENSE-2.0  title: |-    test titlepaths:  /hello:    post:      description: |-        hello world.      operationId: hello      x-apisix-upstream:        type: roundrobin        nodes:          - host: "172.16.238.20"            port: 1980            weight: 1      parameters:        - name: id          in: header          description: ID of pet to use          required: true          schema:            type: string          style: simple
      requestBody:        content:          'application/x-www-form-urlencoded':            schema:              properties:                name:                  description: Update pet's name                  type: string                status:                  description: Updated status of the pet                  type: string              required:                - status      responses:        200:          description: list response        default:          description: unexpected error

configure a route with auth plugins#

notice: for plugin basic-authjwt-auth and key-auth we will use Authentication in OAS3.0

components:  securitySchemes:    basicAuth:      type: http      scheme: basic    BearerAuth:      type: http      scheme: bearer      bearerFormat: JWT    ApiKeyAuth:      type: apiKey      in: header      name: X-API-Keyopenapi: 3.0.0info:  version: "1"  description: |-    test desc  license:    name: Apache License 2.0    url: http://www.apache.org/licenses/LICENSE-2.0  title: |-    test titlepaths:  /hello:    post:      description: |-        hello world.      operationId: hello      x-apisix-upstream:        type: roundrobin        nodes:          - host: "172.16.238.20"            port: 1980            weight: 1      security:        - basicAuth: []        - ApiKeyAuth: []        - BearerAuth: []      responses:        200:          description: list response        default:          description: unexpected error

configure a route with exist service or upstream#

notice: if the service_id or upstream_id does not exist in APISIX, import route from the config file will get an error

openapi: 3.0.0info:  version: 1.0.0-oas3  description: test desc  license:    name: Apache License 2.0    url: 'http://www.apache.org/licenses/LICENSE-2.0'  title: test titlepaths:  /hello:    get:      description: hello world.      operationId: hello      x-apisix-service_id: service1      responses:        '200':          description: list response        default:          description: unexpected error

configure more than one route#

info:  title: RoutesExport  version: 3.0.0openapi: 3.0.0paths:  /get:    delete:      operationId: api1Delete      requestBody: {}      responses:        default:          description: ''      x-apisix-enableWebsocket: false      x-apisix-labels:        API_VERSION: v2        dev: test      x-apisix-plugins:        proxy-rewrite:          disable: false          scheme: https      x-apisix-priority: 0      x-apisix-status: 1      x-apisix-upstream:        nodes:          - host: httpbin.org            port: 443            weight: 1        type: roundrobin        pass_host: node      x-apisix-vars: []    get:      operationId: api1Get      requestBody: {}      responses:        default:          description: ''      x-apisix-enableWebsocket: false      x-apisix-labels:        API_VERSION: v2        dev: test      x-apisix-plugins:        proxy-rewrite:          disable: false          scheme: https      x-apisix-priority: 0      x-apisix-status: 1      x-apisix-upstream:        nodes:          - host: httpbin.org            port: 443            weight: 1        type: roundrobin        pass_host: node      x-apisix-vars: []  /post:    post:      operationId: test_post      requestBody: {}      responses:        default:          description: ''      security: []      x-apisix-enableWebsocket: false      x-apisix-labels:        API_VERSION: v1        version: v1      x-apisix-plugins:        proxy-rewrite:          disable: false          scheme: https      x-apisix-priority: 0      x-apisix-status: 1      x-apisix-upstream:        nodes:          - host: httpbin.org            port: 443            weight: 1        type: roundrobin        pass_host: node      x-apisix-vars: []