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.
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 fields | APISIX Route Properties |
|---|---|
| x-apisix-plugins | plugins |
| x-apisix-script | script |
| x-apisix-upstream | upstream |
| x-apisix-host | host |
| x-apisix-hosts | hosts |
| x-apisix-remote_addr | remote_addr |
| x-apisix-priority | priority |
| x-apisix-vars | vars |
| x-apisix-filter_func | filter_func |
| x-apisix-labels | labels |
| x-apisix-enable_websocket | enable_websocket |
| x-apisix-status | status |
| x-apisix-service_id | service_id |
| x-apisix-upstream_id | upstream_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 upstream x-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
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:
Example:
# this part of information will be missed openapi: 3.0.0 info: 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 ...
Example:
# this part of information will be missed ... servers: - url: https://api.example.com/v1 ...
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 ...
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 ...
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 ...
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.0 info: 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 paths: /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
notice: most plugins supported by extended field x-apisix-plugins
openapi: 3.0.0 info: 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 paths: /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
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.0 info: version: "1" description: |- test desc license: name: Apache License 2.0 url: http://www.apache.org/licenses/LICENSE-2.0 title: |- test title paths: /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
notice: for plugin basic-auth、jwt-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-Key openapi: 3.0.0 info: version: "1" description: |- test desc license: name: Apache License 2.0 url: http://www.apache.org/licenses/LICENSE-2.0 title: |- test title paths: /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
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.0 info: 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 paths: /hello: get: description: hello world. operationId: hello x-apisix-service_id: service1 responses: '200': description: list response default: description: unexpected error
info: title: RoutesExport version: 3.0.0 openapi: 3.0.0 paths: /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: []
Currently we reject import duplicate route, that is to say when you import a route which has the same attributes, all of the URI、Host、URIs、Host、RemoteAddrs、RemoteAddr、Priority、Vars and FilterFunc, as the existing route, you will get an error while importing a route from OAS3.0.