Hello, I’m Tree jam. I wrote a post in the middle of last year on how to better manage apis. Recently, a friend asked me that we all “read” THE CRUD(add, Delete, check and modify) API of every micro service contained in Swagger document, and then manually “masturbate” various service files to achieve encapsulation results. But this will expose some problems, as follows 👇

  • If an interface changes, such as migrating from v1 to V2, a lot of work is required
  • Each time I add a project, I need to encapsulate a set of services and repeat the wheel.
  • The team adds new members, writes repetitive interface packages, and so on

What can be done to solve the above problems? There are ways to do this, essentially by automating programs to generate various service files. So how do you do that? We can parse the structure of the Swagger interface document

What is Swagger/OpenAPI?

Before we talk about parsing documents, we need to take a look at OpenAPI 👇

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

By defining your API with the OpenAPI specification, you can use document generation tools to showcase your API, and even code generation tools to automatically generate server-side and client-side code for a variety of programming languages.

👧 : What is the relationship between openAPI and Swagger?

OpenAPI began with the Swagger specification, which was renamed OpenAPI after it was donated to the Linux Foundation in 2015. The latest specification is defined as OpenAPI 3.0

Essentially you can think of the former as a specification and the latter as a tool to implement the specification 👇

  • OpenAPI = specification
  • Swagger = tools to implement specifications

👦 Ah Le: What does an object implemented by the OpenAPI specification look like?

This includes the following fields (referring to OpenAPI 3.0)

If you want a live preview of OpenAPI’s online editing, try using The Swagger Editor

👦 Ah stay students: I see there are two specifications, OAS2 and OAS3, what is the difference between these two?

OAS2 is short for Swagger2. As mentioned above, after the Swagger specification was donated to Linux, the Swagger specification was renamed as OpenAPI specification, which is OAS3 mentioned by us. Below is the distinction between the two 👇

Recommended reading:

  • Apifox-openapi Specification (Chinese version)

How to parse Swagger/OpenAPI?

Having combed through the OpenAPI specification structure, we now need to parse the OpenAPI document structure to generate our service file

I found two current solutions in the community 👇

2.1 @ umijs/plugin – openapi plug-in

Umijs encapsulates an OpenAPI plug-in. You can automatically create a service by entering an OpenAPI specification file.

This specification file is available in the swagger-UI interface

Then copy the SWAGger URL to the OpenAPI configuration (schemaPath parameter) as shown in the following figure at 👇

The following directory structure is then automatically generated by executing the command line

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

Also in serves we will generate typings. D. ts files that contain the openAPI definitions

The current disadvantage of this tool is that it is heavily bound to UMI and not friendly to Chinese support. If you don’t feel like it fits inside the tech stack, look at the tool’s implementation ideas and build your own wheels from it

2.2 Localization tool generation

The OpenApi community has opened source the OpenApi Generator, through which we can automatically generate API client libraries, documentation and configurations by providing OpenApi specifications (OAS2 and OAS3 mentioned above).

For example, if our front-end relies on AXIos as a request library, we can specify the type to generate ts+ AXIos request-related code

For details, see 🔗 github – Openapi-Generator

If you’re on the front end and not familiar with Java, you’ll be limited by the technology stack because it comes with a JAR package, and while cli tools are available, it only supports YML parsing

So is there a more editable way to use it that doesn’t depend on the environment?

Here’s a tool you can use directly: Apifox

Apifox not only supports mock functions and interface debugging, but I also found a code generation function. The code generation engine uses the openAPI-Generator, which can be defined according to the interface/model. Automatically generates business code, such as interface request code, in various languages/frameworks (TypeScript, Java, Go, Swift, 130 other languages and frameworks)

Above is the interface for generating code, using the TypeScript language + AXIos request library as an example. We can also choose what we export code to include, such as interface code only, model only, etc

3. The last

If you have a better way to achieve, you can also leave a message in the comment section, you can also add my wechat, we drink tea together 🍵 discussion

Previous popular articles 📖 :

  • These Node open Source tools are worth owning
  • Developing visual Data Screens from 0 to 1 (PART 1)
  • Developing visual data Screens from 0 to 1 (part 2)
  • Construction of front-end Knowledge System of Tree Jam (PART 1)
  • Construction of front-end Knowledge System of Tree Jam (Part 2)
  • Talk about daily collaboration tools for front-end development
  • Babel configuration is stupid
  • How to better manage the Api
  • The interviewer asks you about Node
  • Front-end engineering stuff
  • Did you learn BFF and Serverless
  • Front-end operations and deployment

Hello, I am 🌲 tree sauce, please drink a cup 🍵 remember three lian oh ~

1. Remember to click a thumbs-up after reading oh, there is 👍 motivation

2. Pay attention to the interesting things at the front of the public account, and chat with you about the interesting things at the front

3. Github frontendThings thanks to Star✨