With the development of Internet technology, the current website architecture has basically changed from the original back-end rendering to the form of front-end rendering and separation of front-end and back-end, and front-end technology and back-end technology are going further and further on their own roads.
The only connection between the front-end and the back-end has become an API interface; API documentation has become the link between front-end and back-end developers, and it has become more and more important. It swaggeris a framework that allows you to better write API documentation.
Other API Documentation Tools
Before there was no API documentation tool, everyone wrote API documents by hand, wherever they were written, some were confluencewritten above, some were written in the corresponding project directory readme.md, and each company had its own way of playing. It doesn't matter whether it's good or bad.
There are many tools for writing API documents, but it is estimated that there is only one that can be called a "framework" swagger.
Let's first introduce another API documentation tool, called rap , which can be summed up in one sentence: liberate productivity and replace handwritten API web tools. RAPIt is indeed faster to write than handwritten documents, just look at the picture to know:
you can select a project and write an API for a project
Please see, the request and corresponding fields can be filled in
You can also select the type corresponding to the field
There are many similar API documentation tools on the Internet, but there are not many that can be used on the table. RAPIt was developed by Ali, and the whole Ali is using it, which is not bad. The github address is: https://github.com/thx/RAP
Of course, rapit is impossible to only have an online version, and it can definitely be deployed to private servers.
https://github.com/thx/RAP/wiki/deploy_manual_cn
swagger
rapNice, but a bit lightweight compared to swagger.
Let's take a look at the ecological usage diagram of swagger:
Among them, the red color is swagggerrecommended by the official website.
Let's take a closer look at the specific content of swagger's ecology:
swagger-ui
This thing can be seen from the name, used to display API documentation. And rapthe difference is that it is not editable.
Click on a detailed API to try.
swagger-editor
It is a tool for online editing of document description files (swagger.json or swagger.yaml files) to facilitate the use of other gadgets (swagger-ui) in the ecosystem.
Edit on the left, and the editing content will be displayed immediately on the right.
Editing the swagger description file uses the yamlgrammar. The specific content can be viewed on the official website.
A tool for generating swagger documentation based on annotations or annotations in various language versions
The most popular method at present is to write swagger-related comments in the code comments, and then use the gadget to generate the swagger.json or swagger.yaml file.
There is currently no official release. There are various frameworks in various languages and various frameworks on github. You can search for it yourself. Here is only one related to php. swagger-php : https://github.com/zircote/swagger-php
swagger-validator
This small tool is used to verify that the generated documentation is grammatically correct. The usage is very simple, just need the url address bar, add a parameter url under the root path, and the parameter content is the address of the swagger description file. can be verified.
For example:
The docker hub address is: https://hub.docker.com/r/swaggerapi/swagger-validator/
You can pull the image to play by yourself.
swagger-codegen
Code generator, scaffolding. The code of the specified computer language and the specified framework can be generated according to the swagger.json or swagger.yml file.
There is a certain use, and the Java system is used a lot. It should not be used in industry.
mock server
At present, no suitable mock tool has been found, including rap and other API documentation tools, but they are not perfect. Most of them generate some dead static mock data according to the description files, such as swagger.json, etc. Be able to make reasonable responses based on limited conditions: such as "only numbers, must be passed", etc.