Application Programming Interface (API) is an Application Programming Interface. The reason for this, I thought, might be that we humans are intelligent enough to conduct complex verbal communication, such as: “How much is this watermelon?” “Two yuan a catty.” “Give me half.” But computer programs are retarded, and in order for them not to misunderstand our commands, they need a certain format to communicate with them. With apis, our programs have ears and mouths to listen to and answer to. For programmers, if you write a good API, your program will be able to hear and speak well, which naturally adds to your ability.

This road is not an easy one. There are many difficulties and obstacles, with the hidden demons and demons standing in the way. It requires your perseverance and courage to learn modestly and try bravely. Fortunately, we have some great weapons to help you design an API that works. With a basic grasp of these weapons, we can look at some successful business cases, understand their API design, observe their strengths and weaknesses, and finally design and implement our own API.

A Swagger,

Swagger is a specification for describing apis and a tool for generating API documentation.

There are two versions of Swagger, commonly used as 2.0. 3.0 is said to be better, but Postman doesn’t support it. Here’s how to write 2.0:

swagger: '2.0'
Copy the code

This is a YAML file, by the way, used to write configuration information. It’s actually very easy to read, with the key on the left and the value on the right. If you move value to the next line, you need two Spaces to indent it. The one with the minus sign on the right is an element in the list. List as value does not need indentation.

tags:
- name: Accounts
- name: Orders
- name: Products
Copy the code

Tags are tags for each API, and here we define three tags with different names.

While Swagger is a great tool for writing API documentation, documentation is for people to see, and sometimes written documentation is more detailed and clear than what Swagger generates. Overall, writing swagger well can give us a general idea of what the business needs. This is a butterfly knife, used to become a master, beginners can also be used to cut fruit.