You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by ma...@apache.org on 2021/04/01 00:47:11 UTC
[apisix-dashboard] branch master updated: doc: add more details and
examples to import openapi guide (#1672)
This is an automated email from the ASF dual-hosted git repository.
majunjie pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix-dashboard.git
The following commit(s) were added to refs/heads/master by this push:
new a409f75 doc: add more details and examples to import openapi guide (#1672)
a409f75 is described below
commit a409f75b82fb7fbec9f97d3acc2ede90de99269f
Author: liuxiran <li...@apache.org>
AuthorDate: Wed Mar 31 19:47:03 2021 -0500
doc: add more details and examples to import openapi guide (#1672)
Co-authored-by: 琚致远 <ju...@apache.org>
---
docs/en/latest/IMPORT_OPENAPI_USER_GUIDE.md | 427 ++++++++++++++++++++++++++--
1 file changed, 408 insertions(+), 19 deletions(-)
diff --git a/docs/en/latest/IMPORT_OPENAPI_USER_GUIDE.md b/docs/en/latest/IMPORT_OPENAPI_USER_GUIDE.md
index 45c5d15..297c845 100644
--- a/docs/en/latest/IMPORT_OPENAPI_USER_GUIDE.md
+++ b/docs/en/latest/IMPORT_OPENAPI_USER_GUIDE.md
@@ -21,34 +21,21 @@ title: Import OpenAPI Guide
#
-->
-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](https://swagger.io/specification/)(we will use OAS3.0 for short) files to create the Route. Currently we support support most of the OpenApi specifications, but there are some differences, which are in terms of compatibility and extended fields.
-
-## OAS3.0 Compatibility
-
-when we import routes from OAS3.0, some fields in OAS will be missed because there are not corresponding fields in APISIX's Route:
-
-1. [API General Info](https://swagger.io/docs/specification/api-general-info/): used to describe the general information about your API, some times, a oas 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.
-
-2. [API server and base path](https://swagger.io/docs/specification/api-host-and-base-path/): upsream url + url prefix(options).
+## Overview
-3. [Path params](https://swagger.io/docs/specification/describing-parameters/): api params described in path.
+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.
-4. [Query params](https://swagger.io/docs/specification/describing-parameters/): api params described in query.
-
-5. [Responses description and links](https://swagger.io/docs/specification/describing-responses/): Define the responses for a API operations.
+Apache APISIX Dashboard supports importing [OpenApi3.0](https://swagger.io/specification/)(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, we added some extended fields such as upstream, plugins, hosts and so on. All extensions start with x-apisix. See [reference](https://apisix.apache.org/docs/apisix/admin-api/#route) For more details of the APISIX Route Properties
+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-service_protocol | service_protocol |
| x-apisix-host | host |
| x-apisix-hosts | hosts |
| x-apisix-remote_addr | remote_addr |
@@ -58,5 +45,407 @@ There are some fields required in APISIX Route but are not included in the prope
| x-apisix-labels | labels |
| x-apisix-enable_websocket | enable_websocket |
| x-apisix-status | status |
-| x-apisix-create_time | create_time |
-| x-apisix-update_time | update_time |
+| 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.
+
+```yaml
+...
+# 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](https://apisix.apache.org/docs/apisix/admin-api/#route) 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](https://swagger.io/docs/specification/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:**
+
+```yaml
+# 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
+...
+```
+
+2. [API server and base path](https://swagger.io/docs/specification/api-host-and-base-path/): upsream url + url prefix(options).
+
+**Example:**
+
+```yaml
+# this part of information will be missed
+...
+servers:
+ - url: https://api.example.com/v1
+...
+```
+
+3. [Path params](https://swagger.io/docs/specification/describing-parameters/): api params described in path.
+
+**Example:**
+
+```yaml
+# 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
+...
+```
+
+4. [Query params](https://swagger.io/docs/specification/describing-parameters/): api params described in query.
+
+**Example:**
+
+```yaml
+...
+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
+...
+```
+
+5. [Responses description and links](https://swagger.io/docs/specification/describing-responses/): Define the responses for a API operations.
+
+**Example:**
+
+```yaml
+...
+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_
+
+```yaml
+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
+```
+
+### configure a route with plugins
+
+_notice: most plugins supported by extended field `x-apisix-plugins`_
+
+```yaml
+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
+```
+
+### configure a route with parameters validation
+
+_notice: for plugin [request-validation](https://apisix.apache.org/docs/apisix/plugins/request-validation), we will use [Parameter Serialization](https://swagger.io/docs/specification/serialization/) for header parameters validation and [Describing Request Body](https://swagger.io/docs/specification/describing-request-body/) for body parameters validation in OAS3.0_
+
+```yaml
+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
+```
+
+### configure a route with auth plugins
+
+_notice: for plugin [basic-auth](https://apisix.apache.org/docs/apisix/plugins/basic-auth)、[jwt-auth](https://apisix.apache.org/docs/apisix/plugins/jwt-auth) and [key-auth](https://apisix.apache.org/docs/apisix/plugins/key-auth) we will use [Authentication](https://swagger.io/docs/specification/authentication/) in OAS3.0_
+
+```yaml
+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
+```
+
+### 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_
+
+```yaml
+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
+```
+
+### configure more than one route
+
+```yaml
+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: []
+```
+
+## FAQ
+
+1. What is the default strategy when import a duplicate route?
+
+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.