A high-quality interface documentation tool is essential for front and rear joint debugging. Otherwise, the front and back office personnel will keep communicating back and forth, wasting a lot of time. In most enterprises, the swaager is used in the interface document, and perhaps the only drawback is that the ui style is not particularly awesome. However, there are a number of enhanced tools available, such as yapi, which supports the presentation of swagger export files.

If you choose another interface documentation tool, it may be missing compared with swagger. Please choose carefully.

When the blogger specifies the definition by the company, the input parameter value and return value are entity classes, and other basic types of encapsulation types are not allowed. The following uses are based on this premise. Here is the problem of the get request. If you are interested, you can continue to look down.

1. Integrate springboot

1. Addition of POM file

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.2.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.2.2</version>
        </dependency>

2. Add config file

@Configuration
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //controller package
                .apis(RequestHandlerSelectors.basePackage("com.airboot.bootdemo.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("document title")
                .description("Document description")
                .termsOfServiceUrl("http://blog.csdn.net/saytime")
                .version("1.0")
                .build();
    }
}

3. Add notes in application

The @ EnableSwagger2 annotation needs to be added here.

@SpringBootApplication
@EnableSwagger2
public class BootdemoApplication {

    public static void main(String[] args) {
        SpringApplication.run(BootdemoApplication.class, args);
    }

}

After the above steps are completed, it can be used and accessed http://localhost: [port] / swagger-ui.html#/

Attached document structure

2. The interface uses swagger2

1. Modify entity class

If the returned entity class has a Chinese name, the following configuration is required.

@ApiModel(value="DemoVO",description="object")
public class DemoVO {

    private static final long serialVersionUID = -1L;

    /**
     * City number
     */
    @ApiModelProperty(value="id",name="id")
    private Long id;

    /**
     * Province number
     */
    @ApiModelProperty(value="Province number",name="Province number")
    private Long provinceId;

    /**
     * City name
     */
    @ApiModelProperty(value="City name",name="City name")
    private String cityName;

    /**
     * describe
     */
    @ApiModelProperty(value="describe",name="describe")
    private String description;

2. Modify the interface

1. The input parameter is String and the output parameter is List

This method is not allowed in the blogger company.

/**
     * Query by parameter (multiple input parameters)
     *
     * @return
     */
    @RequestMapping(value = "/selectDemoByParas", method = RequestMethod.GET)
    @ApiOperation(value = "Query city information", notes = "Query cities according to input parameters demo(Input parameter is Long)")//notes description
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "Primary key", required = true, dataType = "Long", paramType = "path"), //Required is required. dataType is the input parameter type
            @ApiImplicitParam(name = "provinceId", value = "province id", required = false, dataType = "Long", paramType = "path")
    })
    @ApiResponses(value = {
            @ApiResponse(code = 200, message = "success"),
            @ApiResponse(code = 400, message = "Parameter format error"),
            @ApiResponse(code = 401, message = "Login error"),
            @ApiResponse(code = 404, message = "Address not found"),
            @ApiResponse(code = 500, message = "Server error")}
    )
    public List<DemoVO> selectDemoByParas(@RequestParam("id") Long id, @RequestParam("provinceId") Long provinceId) {
        DemoVO inputVO = new DemoVO();
        inputVO.setId(id);
        return demoService.selectDemoVO(inputVO);
    }

The above is the document effect. At the same time, the model and model schema under the responses class can change the style of the returned object.

You can test the interface through try it out, and switch the Chinese name and json format of the displayed comments.

2. The input parameter is an entity and the output parameter is a list

1.post mode

@RequestMapping(value = "/selectDemoByVo", method = RequestMethod.POST)
    @ApiOperation(value = "Query city information", notes = "Query cities according to input parameters demo")
    //There are three ways to enter parameters in pojo
    //1.@ApiParam
    //2.@ApiImplicitParam(name = "demoVO", value = "VO", required = false, dataType = "DemoVO") 
    //3.@ApiImplicitParams({
            //@ApiImplicitParam(name = "id", value = "primary key", required = true, dataType = "Long", paramType = "path"),
            //@ApiImplicitParam(name = "provinceId", value = "province id", required = false, dataType = "Long", paramType = "path")
    //})
    //!!!! However, it is recommended to use @ ApiParam, which can display the input / output parameter format and Chinese name, for example
    public List<DemoVO> selectDemoByVo(@RequestBody @ApiParam(name = "User object", value = "afferent json format", required = true) DemoVO demoVO) {
        return demoService.selectDemoVO(demoVO);
    }

2.get method

@Log(operationName = "Institutional Department-Query workgroup users")
@GetMapping("/selectWorkSysUser")
@ApiOperation(value = "Query users through entities", notes = "Query users through entities")
public Result<List<SysUserVO>>
selectWorkSysUser(@ApiParam(name = "Input parameter object", value = "entity", required = false) SysUserVO sysSysUserVO) throws TemplateException {
}

The above is the effect. At the same time, the styles of responses class and parameters can be selected.

3. The input parameter is List and the output parameter is List

/**
     * Query by List
     *
     * @param demoVO
     * @return
     */
    @RequestMapping(value = "/selectDemoByList", method = RequestMethod.POST)
    @ApiOperation(value = "Query city information", notes = "Query cities according to input parameters demo")
    @ApiImplicitParam(name = "demoVO", value = "Input parameter is List", required = false, dataType = "List<DemoVO>")
    public List<DemoVO> selectDemoByList(@RequestBody List<DemoVO> demoVO) {
        return demoService.selectDemoVO(demoVO.get(0));
    }

The above is the effect, the same as the above

III. meaning of common notes

    controller Class use
    @Api: Modify the entire class and describe Controller Role of

    @ApiOperation: Describe a method or interface of a class

    @ApiImplicitParams: Multiple request parameters(One@ApiImplicitParams Include multiple 
    @ApiImplicitParam)
    @ApiImplicitParam: A request parameter

    @ApiResponses: HTTP Overall response description(One@ApiResponses Include multiple@ApiResponse)
    @ApiResponse: HTTP Respond to one of the descriptions

    @ApiIgnore: Use this annotation to ignore this API

    @ApiError : Information returned when an error occurs

    @ApiParam: Single parameter description

    Entity class pojo use
    @ApiModel: Receive parameters with objects(pojo Class use)
    @ApiProperty: When receiving parameters with an object, a field describing the object(pojo Parameter usage of class)