juzhiyuan commented on a change in pull request #1672: URL: https://github.com/apache/apisix-dashboard/pull/1672#discussion_r603821046
########## File path: docs/en/latest/IMPORT_OPENAPI_USER_GUIDE.md ########## @@ -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 config the OAS3.0 in different user scenarios + +### config a basic published route Review comment: actually, `config` is not a variable. Use `Configure` here. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: [email protected]
