• Small knowledge, big challenge! This article is participating in the creation activity of “Essential Tips for Programmers”.

Swagger

A, description,

In the modern R&D organizational structure, a R&D team basically includes product group, back-end group, front-end group, APP r&d, testing group, UI group, etc., and each subdivision organization personnel perform their respective duties to jointly complete the full cycle work of the product. How to carry out effective and efficient communication within the organizational structure is particularly important. Among them, how to build a reasonable and efficient interface document is more important. With the development of Internet technology, the current website architecture is basically separated from the original back end into the back end. The only connection between the front and back ends is through the API interface; API documentation becomes increasingly important as a link between front-end and back-end developers.

API documentation

Solution: Complete front-end and back-end development with handwritten documents.

Development documentation Manual:

Wenku.baidu.com/view/f88529…

Problems with handwritten documents

  • When a document needs to be updated, another document needs to be sent to the front-end. That is, the communication between document updates is not timely.
  • The result returned by the interface is not clear
  • Interfaces cannot be tested directly online, usually using tools such as:Postman
  • There are too many interface documents for maintenance and management
  • The document is a static document imported manually by the interface provider and does not provide interface test function

Third, Swagger

1, the introduction of

Swagger. IO/Swagger is a standardized and complete framework for generating, describing, invoking, and visualizing RESTful Web services. The overall goal is to have clients and file systems update at the same rate as servers. File methods, parameters, and models are tightly integrated into server-side code, allowing the API to always be in sync. Swagger is designed to solve this problem. Of course, it cannot be said that Swagger is always perfect. Of course, it also has disadvantages, the most obvious is that the code is highly implanted.

Function:

  1. Interface documents are automatically generated online.

  2. Functional testing.

2. Swagger components

Swagger is a group of open source projects, the main projects are as follows:

  1. Swagger-tools: Provides various tools to integrate and interact with Swagger. For example, pattern checking, Swagger 1.2 documents to Swagger 2.0 documents, and so on.
  2. Swagger-core: The Swagger implementation for Java/Scala. With JAX-RS(Jersey, Resteasy, CXF…) , Servlets, and the Play framework.
  3. Swagger-js: Swagger implementation for JavaScript.
  4. Swagger- Node-Express: Swagger module, used in node.js Express Web application framework.
  5. Swagger-ui: A dependency free collection of HTML, JS, and CSS that dynamically generates elegant documentation for Swagger-compatible apis.
  6. Swagger-codegen: A template-driven engine that generates client-side code in various languages by analyzing user Swagger resource declarations.

Swagger integration

1. Increase Swagger2 dependency

2 Create the Swagger2 configuration class

1. Class description

@Api: used on the requested class to describe the class

Tags =” Notes that describe what this class does, and that you can see on the UI”

Value =” This parameter is meaningless and can be seen on the UI, so it is not needed”

2. Method description

ApiOperation: used in a requested method to describe the purpose of the method

Value =” Notes “=” notes”

3. Description of method parameters

ApiImplicitParams: Used in the request method to represent a set of parameter descriptions

@APIIMPLICITParam: Used in the @APIIMPLICITParams annotation to specify aspects of a request parameter

Name: parameter name

Value: Indicates the Chinese character description of a parameter

Required: Indicates whether the parameter must be passed

ParamType: Where does the parameter go

DefaultValue: indicates the defaultValue of the parameter

4. Method response parameters

@apiresponses: Used in a request method to represent a set of responses

@apiResponse: Used in @apiresponses, usually to express an incorrect response

Code: number, e.g. 400 message: message, e.g. “Request parameters are not filled out.” Response: class that throws an exception