1. What is swagger
Swagger is a normative and complete framework for generating, describing, invoking and visualizing restful style web services. The overall goal is to make the client and file system update at the same speed as the server. File methods, parameters and models are tightly integrated into the server-side code, allowing the API to always keep in sync. Swagger makes it easy to deploy, manage, and use powerful APIs.
Swagger adopts open API specification, which can help you express API more simply and quickly, especially in the design phase of API. Once completed, the API document can be used as:
·The basis of requirement and system characteristic description
·The basis of front and back inquiry, discussion and self-test
·Some or all of the code is automatically generated according to
·Other important functions, such as open platform developer’s manual
2. How to write API documents
1) , define yaml files, and then generate code frameworks of various languages. For background programmers, few people are willing to write a bunch of yaml formats.
2) , define the JSON format file, write the document according to the swagger document writing specification, just two different formats like yaml.
3) Through various language plug-ins of swagger, interface documents and test interfaces can be generated through configuration and a small amount of code. Static documents are written through yaml or JSON, and interface documents can be displayed through visual pages after completion. But it is also very time-consuming to complete the interface document writing of the whole project. If it is the background development, the document can be automatically generated through simple configuration.
3. Application of swagger in API project
Eolink is an integrated interface management tool used in our company, including development, testing and documentation functions. The packaged architecture also reduces a lot of code input work. Let’s use it to demonstrate the docking with swagger.
1) Import swagger file in JSON format directly in eolink interface;
2) Test the written interface directly;
You can directly modify the parameters of a single interface in the details, and the content of the interface document changes in real time with the changes of the interface. Compared with the static document, each change needs to develop and update the document, which is undoubtedly a very good solution.
3) It can export documents in various formats;
Sometimes for external project docking, the other party doesn’t use swagger, but can also export documents in other formats. This is my surprise.