springboot利用swagger构建api文档

0、 swagger简介

swagger是一个功能强大的api框架，它的集成非常简单，不仅提供了在线文档的查阅，而且还提供了在线文档的测试。另外swagger很容易构建restful风格的api，简单优雅帅气，正如它的名字。
简单的来说，Swagger2的诞生就是为了解决前后端开发人员进行交流的时候API文档难以维护的痛点，它可以和我们的Java程序完美的结合在一起，并且可以与我们的另一开发利器Spring Boot来配合使用。

一、导入pom依赖

<!--api框架 在线文档的查阅,测试-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.6.1</version>
</dependency>
或者
<!-- 这里使用 swagger-bootstrap-ui 替代了原有丑陋的ui，拯救处女座~ -->
  <dependency>
      <groupId>com.github.xiaoymin</groupId>
      <artifactId>swagger-bootstrap-ui</artifactId>
      <version>1.9.0</version>
 </dependency>

二、 添加配置类

我们需要新增一个Swagger2Config 的配置类，apiINfo()配置一些基本的信息。apis()指定扫描的包会生成文档：

@Configuration
@EnableSwagger2
public class Swagger2Config {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //这里把扫描的包配置一下
		.apis(RequestHandlerSelectors.basePackage("com.wxmanage.address.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("springboot利用swagger构建api文档")
                .description("简单优雅的restfun风格，https://blog.csdn.net/qq_35456400")
                .termsOfServiceUrl("https://blog.csdn.net/qq_35456400")
                .version("1.0")
                .build();
    }
}

三、写注解

使用第一种UI访问地址：http://localhost:8080/swagger-ui.html
使用第二种UI访问地址：http://localhost:8080/doc.html
注意是再你配置的包下面的类中

1. @Api,修饰整个类，描述Controller的作用

属性	作用
tags	说明该类的作用
value	说明该类的作用

@Api(value = "操作机构",tags = "操作机构信息")
@Log
@RestController
public class InstController {
...
}

2. @ApiOperation ，描述一个类的一个方法，或者说一个接口
   | 属性 | 作用 |
   |–|--|
   | value | 描述方法作用 |
   |notes | 提示内容 |
   | tags | 分组 |
3. @ApiParam：单个参数描述，多个用@ApiImplicitParams

属性	作用
name	参数名
value	参数说明
required	是否必填

@ApiOperation(value="发送删除机构信息到微信后台", notes="发送删除机构信息到微信后台")
@GetMapping("/deleteInst")
public String deleteInst(@ApiParam(name="id",value="用户id",required=true) Long id){

}

4. @ApiModel && @ApiModelProperty
   @ApiModel：用对象来接收参数,修饰类

属性	作用
value	对象名
description	描述

@ApiProperty：用对象接收参数时，描述对象的一个字段，修饰属性

属性	作用
value	字段说明
name	属性名
dataType	属性类型
required	是否必填
example	举例
hidden	隐藏

@ApiModel(value="user对象",description="用户对象user")
@Data
public class User {

    @ApiModelProperty(value = "用户ID",example = "1000001",hidden=true)
    private Long id;

    @ApiModelProperty(value="用户名",required = true,dataType = "String")
    private String userName;

    @ApiModelProperty(value = "密码")
    private String password;
}

5. @ApiImplicitParam && @ApiImplicitParams
   @ApiImplicitParam ：一个请求参数·

属性	作用
value	参数说明
name	参数名
dataType	数据类型
paramType	参数类型
example	举例

@ApiImplicitParams多个请求参数

@ApiImplicitParams({
    @ApiImplicitParam(name="access_token", value = "应用的token", required = true, dataType = "String"),
    @ApiImplicitParam(name="id")
})
@GetMapping("/deleteInst")
public String deleteInst(String access_token,String id){
...
}

6. @ApiResposne && @ApiResponses
   @ApiResponse：HTTP响应其中1个描述

属性	作用
response	返回类
code	返回码
message	返回信息
examples	例子

@ApiResponses：HTTP响应整体描述

7. @ApiIgnore：使用该注解忽略这个API·
8. @ApiError ：发生错误返回的信息

四、 两种UI风格对比

spring-fox的ui
http://localhost:8080/swagger-ui.html
bootstrap风格的ui：
http://localhost:8080/doc.html