liuxiran commented on issue #825: URL: https://github.com/apache/apisix-dashboard/issues/825#issuecomment-745109777
> * Expand OAS3.0, increase `upstream` and `service`, which are required by APISIX, and at the same time provide a detailed documentation. we can refer to aliyun API gateway[1]. > > * advantages: > when users import OAS, they only need to pay attention to the profile and do not need to do any additional works. > we can support batch operations. > this also can be done only as a command-line tool. > * disadvantages: > Users need to modify the existing OAS refer to our doc. > `upstream` and `service` are the only necessary expansiones, if we want to support other plugins by `import` operation, we also need to define new expansion. Based on the first plan, how to transform route configuration to OAS3.0? After further compare the configuration of OAS3.0 and routes in APISIX, we categorized the current route fields into three parts * explicitly matched fields are: | route field | OAS3.0 field| | ---- | ---- | | name | paths[url][method]operationId | | desc | paths[url][method]summary | | methods | paths[url]method | * We can do the conversion to implement the corresponding fields are: | route field | OAS3.0 field| | ---- | ---- | | uris | paths.url, | | vars | | | plugins.key-auth | [OAS3.0 reference](https://swagger.io/docs/specification/authentication/api-keys/) | | plugins.basic-auth | [OAS3.0 reference](https://swagger.io/docs/specification/authentication/basic-authentication//) | | plugins.jwt-auth | [OAS3.0 reference](https://swagger.io/docs/specification/authentication/bearer-authentication/) | | plugins.openid-connect | [OAS3.0 reference](https://swagger.io/docs/specification/authentication/openid-connect-discovery//) | | plugins.request-validation | [header params OAS3.0 reference](https://swagger.io/docs/specification/describing-parameters/) 、[body params OAS3.0 reference](https://swagger.io/docs/specification/describing-request-body/) | * we need to expended fields are: _we recommend to follow the data structure of the route, only change the name of the key, We can define the first supported fields, prefixed with `x-apisix-*`._ | route field | OAS3.0 expanded field| | ---- | ---- | | upstream | paths[url][method]x-apisix-upstream [apisix upstream ref](https://github.com/apache/apisix/blob/master/doc/architecture-design.md#upstream) | | plugins(except for a few plugins mentioned above) | paths[url][method]x-apisix-plugins [apisix plugins ref](https://github.com/apache/apisix/blob/master/doc/architecture-design.md#plugin) | | hosts | paths[url][method]x-apisix-hosts | --- we formed the first phase of development plan below: 1. **Export routes configuration as a json/yaml file in the way we expanded OAS3.0.** BE: new a manager-api params: routeids & filetype(json or yaml) returns: file FE: add select box to each of route items in route list add a button `Export routes as OAS3.0` to the top of the route list select one or more routes, and click the Export button, get the OAS3.0 file 2. **import the exported file to generate routes.** BE: new an API params: file returns: success or failed FE: add a button `Import routes from OAS3.0` at the top of the route list click button, upload file 3. **Document: Write a document to describe our expansion configuration options based on OAS3.0, examples+description.** cc @LiteSun @juzhiyuan @moonming @membphis @nic-chen @gxthrj ---------------------------------------------------------------- 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]
