swagger2 real time generation of interface documents

Swagger is a standardized and complete framework for generating, describing, invoking, and visualizing RESTful style Web services.
The overall goal is to have 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 has never made deployment management and use of powerful API s easier.

1. Introduce Swagger2 and swagger ui (add dependency in parent project)`

	<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
	<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->

2. Write configuration class

package com.swaggeri.test.ctrl;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration //Declare that this is a configuration class
@ComponentScan(basePackages = {"com.swaggeri.test.ctrl"})//Specifies the package path of the class that needs to generate the API document
@EnableSwagger2  //swagger2 launch annotation
public class SwaggerConfig {

    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .contact(new Contact("zy", null, null))
@Configuration Declare that this is a configuration class
@ComponentScan(basePackages = {""}) Specifies the package path of the class that needs to generate the API document
@EnableSwagger2 swagger2 launch annotation

Publish the project startup to tomcat, and you can access the swagger API
The URL accessed is also a fixed format http://localhost:8080/swagger-ui.html

3. Configure api generation

Only @ ComponentScan(basePackages = {"com.swaggeri.test.ctrl"}) will be displayed here. The API generated by the class under this path will be displayed
Only one SwaggerCtrl is written in the test case, so only SwaggerCtrl and its methods are shown here

package com.swaggeri.test.ctrl;
import com.alibaba.fastjson.JSONObject;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;
import javax.servlet.http.HttpServletRequest;

@Api(value = "SwaggerCtrl", description = "Swagger")
public class SwaggerCtrl {
    @ApiOperation(value = "Swagger2 Introduction")
    @RequestMapping(value = "/helloSwagger2", method = RequestMethod.POST)
    public JSONObject helloSwagger2(HttpServletRequest request,
                                    @RequestBody JSONObject obj) {
        JSONObject jsonObject = new JSONObject();
        jsonObject.put("hello", "Swagger2!");
        return jsonObject;


Used on the requested class to indicate the description of the class

  • tags "describes the function of this class. You can see the comments on the UI interface."


Used in the method of request, indicating the purpose and function of the method

  • value = "describe the purpose and function of the method"


Used on the requested method to represent a set of parameter descriptions

​ @ApiImplicitParam

ApiImplicitParam: specify all aspects of a request parameter

value: Chinese character description and explanation of parameter

required: whether the parameter must be passed

paramType: where to put the parameter

Header – > get request header: @ RequestHeader

query – > get request parameters: @ RequestParam

Path (for restful interface) - > obtain the request path variable: @ PathVariable

body (not commonly used)

form (not commonly used)

dataType: parameter type, default String, other values dataType = "Integer"

defaultValue: the default value of the parameter


Used on a request method to represent a set of responses

​ @ApiResponse

Used in @ ApiResponses, generally used to express a wrong response information

code: number, for example 400

Message: message, such as "request parameter is not filled in"

response: the class throwing the exception


There are two main uses:

Used on response classes to represent information that returns response data

Input entity: when @ RequestBody is used, the request parameter cannot be described with @ ApiImplicitParam annotation


Used on properties to describe the properties of the response class

Published 2 original articles, praised 0, and visited 28
Private letter follow

Keywords: Spring Tomcat

Added by webdesco on Tue, 14 Jan 2020 08:37:19 +0200