liuxiran commented on a change in pull request #1672: URL: https://github.com/apache/apisix-dashboard/pull/1672#discussion_r602901727
########## File path: 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). - -3. [Path params](https://swagger.io/docs/specification/describing-parameters/): api params described in path. +## Overview -4. [Query params](https://swagger.io/docs/specification/describing-parameters/): api params described in query. +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. -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, inorder 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. See [reference](https://apisix.apache.org/docs/apisix/admin-api/#route) For more details of the APISIX Route Properties Review comment: fixed, thanks -- 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: us...@infra.apache.org
