springboot-springfox

swagger文档规范的使用

作者一开始使用springfox接入springmvc，但是配置有点复杂。后来转到springboot后相对来讲配置相对较少，下面来讲讲springfox的介入（此插件遵循swagger规范）

pom插件引入

<pre>

  <!-- swagger -->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>${swagger.version}</version>
    </dependency>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>${swagger.version}</version>
    </dependency>

</pre>
具体版本可参考maven仓库

SwaggerConfig

<pre>
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.useDefaultResponseMessages(false);

}

private ApiInfo apiInfo() {
    return new ApiInfoBuilder()
            .title("document api")
            .description("swagger style")
            .version("1.0.0")
            .build();
}

}
</pre>
注意的点@EnableSwagger2以及apiinfo（）里面的信息都是显示在api文档里面用来提醒用户的。

最后具体的接口配置

@Api这个用来标记controller的内部有description用来显示整个controller的内容
@ApiOperation 默认value属性，提示这个接口的操作，可以写入接口方法，数据，头信息，具体可参考官方文档
@ApiImplicitParam 添加在方法上可以提示参数的类型，说明，note属性需添加
@ApiImplicitParams 由多个@ApiImplicitParam组成
@ApiResponse 接口返回信息提示需配置code，message，response等属性
@ApiResonses 由多个@ApiResponse组成
@ApiParam 对单个参数进行注解
@ApiModule 配置需要说明的类型，需要写value属性才能正确显示
@ApiModuleProperty 字段说明

总结

由于无法上传图片就不贴效果图了，最后访问swagger-ui.html就可以了
SpringMvc内配置比较麻烦需要用对资源进行拦截，要下载swagger的资源修改内部的/v2/api-docs链接，相对较为麻烦，有兴趣的同学也可以研究一下