How to better manage the Api interface (continued)

---

Hello, this is tree jam. In the middle of last year, I wrote an article about how to better manage the Api interface . Recently, a friend asked me that we are all based on the Swagger document, and then we "read" the APIs such as CRUD (addition, deletion, check and modification) contained in each microservice in the swagger document, and then "manually" pull out various service files. Achieve the result of packaging. But this will expose some problems, as follows 👇

• If the interface changes, for example, the interface is migrated from v1 to v2, then a lot of transformation is required
• Every time I add a project, I need to encapsulate a set of services. Is it a pleasure to repeat the wheel?
• Add new members to the team, write repeated interface packages, etc.

Is there any way to solve the above problems?
There are methods, in essence, through program automation to generate various service files, freeing hands. How do you do it? We can parse the structure of the swagger interface document

1. What is Swagger / OpenAPI?

Before talking about parsing documents, we first need to understand OpenAPI 👇

The OpenAPI specification, also known as OAS, is an API document standard

By defining your API through the OpenAPI specification, you can use a document generation tool to display your API, and even use a code generation tool to automatically generate server-side and client-side code in various programming languages.

👧 Ah Le: What is the relationship between openAPI and swagger?

OpenAPI started from the Swagger specification. The Swagger specification was donated to the Linux Foundation in 2015 and renamed to OpenAPI, and the latest specification is defined as OpenAPI 3.0

In essence, you can understand that the former is a specification, and the latter is a tool to implement the specification👇

• OpenAPI = specification
• Swagger = tool to implement specifications

👦 Student Ah Le: So what does an object implemented through the OpenAPI specification look like?

Specifically, it mainly includes the following field information (referring to OpenAPI 3.0)

If you want to preview the effect of OpenAPI online editing in real time, you can try Swagger Editor

👦 Ah Dumb classmate: I think there are two specifications, OAS2 and OAS3. What is the difference between the two?

OAS2 is the abbreviation of Swagger2. As mentioned above, since the donation of the Swagger specification to Linux, the Swagger specification was renamed to the OpenAPI specification, which is the OAS3 we mentioned. The picture below is the difference between the two 👇

Recommended reading:

• Apifox-OpenAPI Specification (Chinese version)

2. How to parse Swagger / OpenAPI?

After sorting out the OpenAPI specification structure, then we need to generate our service file by parsing the OpenApi document structure

I found two current solutions in the community👇

2.1 @umijs/plugin-openapi plugin

Umijs encapsulates an openapi plug-in. By entering an openapi specification file, the service can be automatically created.

This specification file can be obtained in the interface through swagger-ui

Then copy the url of swagger to the configuration of openapi (schemaPath parameter), you can refer to the figure below👇

Then execute the command line to automatically generate the following directory structure serves

Here, take the DEMO API document of the pet store as an example to see what the generated interface package looks like

At the same time, we will also generate typings.d.ts file in serves, which contains the definition in openapi

The current disadvantage of this tool is that it is heavily bound to umi and is not friendly to Chinese support. If you feel that it is not suitable for the internal technology stack, you can refer to the implementation ideas of the tool, and then build your own wheels on the basis of it

2.2 Localization tool generation

The OpenApi community has open sourced the OpenApi Generator. We can use OpenAPI Generator to automatically generate API client libraries, documents, and configurations by providing OpenAPI specifications (OAS2 and OAS3 mentioned above).

For example, our front-end relies on axios as the request library, then we can generate the request-related code of ts+axios by specifying the type

For specific use, please refer to 🔗 github-openapi-generator

If you are a front-end and are not familiar with java children's shoes, you will receive technical stack restrictions if you use it directly, because it provides a JAR package. Although there is also a cli tool, it only supports yml format analysis.

So is there a more editing way that can be used independently of the environment?

Here is a tool for you to use directly: Apifox

Apifox not only supports mock functions and interface debugging, but also a code generation function. The code generation engine uses the openapi-generator we mentioned, which can automatically generate various languages/frameworks according to the interface/model definition ( (Such as TypeScript, Java, Go, Swift and other 130 languages and frameworks) business code, such as interface request code

The above picture is Apifox . Here we take the TypeScript language + axios request library as an example. We can also choose the content of the code we export, such as only the interface code or only the model, etc.

3. Finally

If you have a better way to implement it, you can also leave a message in the comment area, or add me on WeChat, let’s have tea together🍵 to discuss