Open Source API Documentation Tool framework--swagger Introduction

The first contact with Swagger was in May 2017, when the company was about to redesign the entire system architecture, and a colleague recommended using this technical framework to standardize the API documentation for the backend interface. At that time, because of the reconstruction of the architecture, involved in the transformation of the technical point too much, a moment will not have much energy, put swagger temporarily put down. For the API documentation we define a template for ourselves, which requires the developer to write the document on the tower.

Now look back, there are a few questions:

1. The timeliness of document writing and modification is not enough, due to the API in the development and testing process is often adjusted, the corresponding documents can not be modified in time.

2. The normative requirements of the document need to be constrained by human inspection, which increases the workload of project management.

3. Front-end and testers have a process of understanding the document, sometimes need to frequent and background developers to communicate, resulting in a certain exchange costs.

Since the current Internet project is the form of front-end cooperation, the only connection between the front end and the back end becomes the API interface, the API document becomes the link that the front and back end developer contacts, becomes more and more important, in this case, I again focus on the swagger. After a few days of research, there is a relatively clear understanding, ready to write a few blog on this technology to explain.

Swagger this word to do adjectives is "show off, fashionable" such a meaning. Website address: Https://swagger.io, the official website of the definition of its project is:

Swagger is the world ' s largest framework of APIs developer tools for the OpenAPI specification (OAS), enabling development A Cross the entire API lifecycle, from design and documentation, to test and deployment.

Swagger is a tool framework for a large API developer that proposes a specification for writing OPENAPI (named OAS), and swagger can be developed across the entire API lifecycle, from design and documentation to testing and deployment.

Swagger the principle of this framework: the framework presents a document specification OAS, and provides a corresponding visual editor to edit this document and verify the document format, the format of the document is XML or JSON form of the file (hereinafter referred to as API meta-file), The API meta-File framework provides a visual representation of API meta-files, which can be used to customize the template in the form of a browser's web page (i.e. an interactive web system) and to support online interaction testing of the AIP interface. The community has also developed a number of integration frameworks to enable swagger to integrate well with frameworks such as SPRINGMVC, and to automatically generate the appropriate API documentation by writing annotations on the controller. More interestingly, Swagger also provides the ability to generate client calling code and service stub code based on API meta-files.

Swagger framework from the macroscopic point of view, I personally think can be divided into three parts:

• Provides a specification for writing API documentation, called OAS, which explicitly formats the API in the specification and some authoring features
• Provide relevant tools to assist in the preparation of API documentation. The main items are so many projects Swagger Editor, Swagger UI, Swagger Codegen, Swagger Inspector.
• Provides integration of a wide range of popular languages and frameworks, such as the Springfox framework for integrating SPRINGMVC

Open Source API Documentation Tool framework--swagger Introduction