Swagger 实战

前言

Swagger主要用于构建接口API，以方法注释的方式自动化生成API，能够应对接口的变化，减少构建API文档的工作量。
一个对外提供的接口，主要包含以下内容:

	- 访问url
	- 请求方式：post or get
	- 请求参数：参数是否必填
	- 返回结果：远程调用都要有规定的错误代码

构建API

ControllerNameController.java

@Api("用在类上，说明该类的作用")
@Controller
@RequestMapping("/api/ControllerName")
public class ControllerNameController {

    @ApiOperation(value = "方法说明", notes = "注释，一般出现在方法说明的下方")
    @ApiResponses({
            @ApiResponse(code = 0, message = "系统提示信息：请求成功"), 
            @ApiResponse(code = 1, message = "系统提示信息：请求失败原因")
    })
    @ApiImplicitParams({
            @ApiImplicitParam(paramType = "query", name = "param1", value = "param1 参数说明", required = true, dataType = "String", defaultValue = "param1 default value"),
            @ApiImplicitParam(paramType = "query", name = "param2", value = "param2 参数说明", required = false, dataType = "Integer", defaultValue = "param2 default value")
    })
    @PostMapping("/methodName")
    @ResponseBody
    public TableDataInfo methodName(@RequestParam(name = "param1")String param1,
                                    @RequestParam(name = "param2")Date param2)
    {
        
    }
}

配置swagger

Maven依赖

<properties>
	<swagger.version>2.9.2</swagger.version>
</properties>

<dependency>
	<groupId>io.springfox</groupId>
	    <artifactId>springfox-swagger2</artifactId>
		<version>${swagger.version}</version>
		<exclusions>
		    <exclusion>
		        <groupId>io.swagger</groupId>
				<artifactId>swagger-annotations</artifactId>
		    </exclusion>
		    <exclusion>
		        <groupId>io.swagger</groupId>
				<artifactId>swagger-models</artifactId>
		    </exclusion>
	    </exclusions>
</dependency>
<!-- swagger2-UI-->
<dependency>
    <groupId>io.springfox</groupId>
	<artifactId>springfox-swagger-ui</artifactId>
	<version>${swagger.version}</version>
</dependency>

SwaggerConfig.java

/**
 * Swagger2的接口配置
 * @Author waichan
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig
{
    /**
     * 创建API
     */
    @Bean
    public Docket createRestApi()
    {
        return new Docket(DocumentationType.SWAGGER_2)
                // 用来创建该API的基本信息，展示在文档的页面中（自定义展示的信息）
                .apiInfo(apiInfo())
                // 设置哪些接口暴露给Swagger展示
                .select()
                // 扫描所有有注解的api，用这种方式更灵活
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                // 扫描指定包中的swagger注解
                //.apis(RequestHandlerSelectors.basePackage("com.waichan.web.controller.project.api"))
                // 扫描所有 .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 添加摘要信息
     */
    private ApiInfo apiInfo()
    {
        // 用ApiInfoBuilder进行定制
        return new ApiInfoBuilder()
                // 设置标题
                .title("标题：接口文档")
                // 描述
                .description("描述：对外接口文档")
                // 作者信息
                .contact(new Contact("waichan", "https://blog.csdn.net/DMW2016", "594235081@qq.com"))
                // 版本
                .version("版本号:" + "version")
                .build();
    }
}

链接

Swagger.io