Swagger2 engine configuration interface documentation

The problem there is a handwritten document

Documentation needs to be updated, need to send a copy to the front again, that is not timely exchange of documentation updates.
Interface returns the result is not clear
Can not direct online test interface, usually requires the use of tools, such as: Postman
Too many interface documentation, poor management

Use Swagger to solve the problem

Swagger is to solve this problem, of course, can not say that Swagger will certainly be perfect, of course, also has drawbacks, the most obvious is the code into relatively strong.

Maven

Dependent increase Swagger2 desired, pom.xmlconfigured as follows:

<!-- Swagger2 Begin -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.8.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.8.0</version>
</dependency>
<!-- Swagger2 End -->

Configuration Swagger2

Note: RequestHandlerSelectors.basePackage("com.funtl.itoken.service.admin.controller")for the Controller package path, or less than a generation document scanning interfaces
That service requires a separate creation
Create a file called Swagger2Configthe Java class configuration, as follows:

package com.funtl.itoken.service.admin.config;

import org.springframework.context.annotation.Bean;
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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
public class Swagger2Config {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.funtl.itoken.service.admin.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("iToken API 文档")
                .description("iToken API 网关接口，http://www.funtl.com")
                .termsOfServiceUrl("http://www.funtl.com")
                .version("1.0.0")
                .build();
    }
}

Enable Swagger2

Application make a comment @EnableSwagger2will indicate on Swagger

package com.funtl.itoken.service.admin;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.netflix.eureka.EnableEurekaClient;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import tk.mybatis.spring.annotation.MapperScan;

@SpringBootApplication(scanBasePackages = "com.funtl.itoken")
@EnableEurekaClient
@EnableSwagger2
@MapperScan(basePackages = {"com.funtl.itoken.common.mapper", "com.funtl.itoken.service.admin.mapper"})
public class ServiceAdminApplication {
    public static void main(String[] args) {
        SpringApplication.run(ServiceAdminApplication.class, args);
    }
}

Use Swagger2

Increase in the Controller Swagger2related annotations, as follows:

/**
 * 分页查询
 *
 * @param pageNum
 * @param pageSize
 * @param tbSysUserJson
 * @return
 */
@ApiOperation(value = "管理员分页查询")
@ApiImplicitParams({
        @ApiImplicitParam(name = "pageNum", value = "页码", required = true, dataType = "int", paramType = "path"),
        @ApiImplicitParam(name = "pageSize", value = "笔数", required = true, dataType = "int", paramType = "path"),
        @ApiImplicitParam(name = "tbSysUserJson", value = "管理员对象 JSON 字符串", required = false, dataTypeClass = String.class, paramType = "json")
})
@RequestMapping(value = "page/{pageNum}/{pageSize}", method = RequestMethod.GET)
public BaseResult page(
        @PathVariable(required = true) int pageNum,
        @PathVariable(required = true) int pageSize,
        @RequestParam(required = false) String tbSysUserJson
) throws Exception {

    TbSysUser tbSysUser = null;
    if (tbSysUserJson != null) {
        tbSysUser = MapperUtils.json2pojo(tbSysUserJson, TbSysUser.class);
    }
    PageInfo pageInfo = adminService.page(pageNum, pageSize, tbSysUser);

    // 分页后的结果集
    List<TbSysUser> list = pageInfo.getList();

    // 封装 Cursor 对象
    BaseResult.Cursor cursor = new BaseResult.Cursor();
    cursor.setTotal(new Long(pageInfo.getTotal()).intValue());
    cursor.setOffset(pageInfo.getPageNum());
    cursor.setLimit(pageInfo.getPageSize());

    return BaseResult.ok(list, cursor);
}

Swagger explanatory notes

Swagger by annotation indicates that this interface will generate documentation, including interface name, request methods, parameters, return information, and so on.

@Api: Modification of the entire class, describe the role of Controller
@ApiOperation: Describes a method of a class or an interface
@ApiParam: Single Parameter Description
@ApiModel: Receiving the object parameters
@ApiProperty: Upon receiving the object parameters, a description of the object field
@ApiResponse: HTTP response is described wherein a
@ApiResponses: HTTP response Overall description
@ApiIgnore: Use this API to ignore this comment
@ApiError: Information occurred error is returned
@ApiImplicitParam: A request parameter
@ApiImplicitParams: A plurality of request parameters