Swagger是一个简单但功能强大的API表达工具。它具有地球上最大的API工具生态系统，数以千计的开发人员，使用几乎所有的现代编程语言，都在支持和使用Swagger。使用Swagger生成API，我们可以得到交互式文档，自动生成代码的SDK以及API的发现特性等。
现在，Swagger已经帮助包括Apigee, Getty图像, Intuit, LivingSocial, McKesson, 微软, Morningstar和PayPal等世界知名企业建立起了一套基于RESTful API的完美服务系统。
2.0版本已经发布，Swagger变得更加强大。值得感激的是，Swagger的源码100%开源在github。
swagger

在Spring中使用Swagger文档

导包

在SpringBoot的pom.xml文件中加入依赖，空串问题在另一篇blog有写

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
<!-- Swagger2 Api插件 -->
      <dependency>
          <groupId>io.springfox</groupId>
          <artifactId>springfox-swagger2</artifactId>
          <version>2.9.2</version>
          <!--排除swagger-models1.5.20版本，解决空串问题-->
          <exclusions>
              <exclusion>
                  <groupId>io.swagger</groupId>
                  <artifactId>swagger-models</artifactId>
              </exclusion>
          </exclusions>
      </dependency>
      <!--导入swagger-models1.5.22版本，解决空串问题-->
      <dependency>
          <groupId>io.swagger</groupId>
          <artifactId>swagger-models</artifactId>
          <version>1.5.22</version>
      </dependency>

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

配置Swagger

在项目中Application.java同级创建Swagger的配置类

1
2
3
4
5
6
@Component
// 开启Swagger2的自动配置
@EnableSwagger2
public class Swagger2Config {
    
}

配置Swagger实例

Swagger实例Bean是Docket，所以通过配置Docket实例来配置Swaggger

1
2
3
4
5
6
@Bean
    public Docket creatRestApi(){
        
        return new Docket(DocumentationType.SWAGGER_2);
        
    }

然后启动项目，打开http://localhost:8080/swagger-ui.html即可看到接口文档

Swagger文档页面

配置要扫描的接口

1
2
3
4
5
6
7
8
9
10
@Bean
    public Docket creatRestApi(){

        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors
                .basePackage("com.ego14t.xinmusic.controller")) //Controller所在的包
                .build();

    }

RequestHandlerSelectors中还有一些其他的扫描方式

  1. any() ：扫描所有，项目中的所有接口都会被扫描到
  2. none()：不扫描接口
  3. withMethodAnnotation(final Class<? extends Annotation> annotation)：通过在方法上注解扫描如withMethodAnnotation(GetMapping.class)只扫描get请求
  4. withClassAnnotation(final Class<? extends Annotation> annotation)：通过类上的注解扫描，如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口

配置Api文档信息

1
2
3
4
5
6
7
8
9
//配置文档信息
   private ApiInfo apiInfo() {
       return new ApiInfoBuilder()
               .title("昕音乐Api文档")
               .description("优雅的Api文档")
               .version("1.0")
               .build();

   }

具体可以配置的参数如下：

1
2
3
4
5
6
7
8
9
10
11
	//联系人信息 name，url，email
public static final Contact DEFAULT_CONTACT = new Contact("", "", "");
   public static final ApiInfo DEFAULT;//默认值
   private final String version;//版本号
   private final String title;//标题
   private final String description;//接口描述
   private final String termsOfServiceUrl;//组织链接
   private final String license;//许可
   private final String licenseUrl;//许可链接
   private final Contact contact;//联系人
   private final List<VendorExtension> vendorExtensions;

完成

swagger

Api的详细信息配置

  1. @Api：作用于控制器类上，标识这个类是Swagger资源，tags值会在页面显示
1
@Api(value = "歌单Controller",tags = {"歌单操作类接口"})

  1. @ApiOperation：作用于方法上，表示一个http请求的操作，value用于方法描述 ，notes用于提示内容
1
2
//tags会添加分组，视情况用
@ApiOperation(value="根据歌单id返回歌曲列表",tags={""},notes="注意问题点")

  1. @ApiImplicitParams() ：用于方法，参数，字段说明，标识请求参数name参数名，value参数说明，dataType数据类型 ，paramType参数类型 ，example–举例说明，required是否必填

    1
    @ApiImplicitParam(paramType="query", name = "id", value = "歌单ID", required = true, dataType = "int")
    1
    2
    3
    @ApiImplicitParams({
      @ApiImplicitParam(paramType="query", name = "id", value = "歌单ID", required = true, dataType = "int"),
      @ApiImplicitParam(paramType="query", name = "username", value = "用户名", required = true, dataType = "String")})

  2. ApiImplicitParam中的paramType参数

    paramType参数 请求参数的获取
    header @RequestHeader(代码中接收注解)
    query @RequestParam(代码中接收注解)
    path（用于restful接口） @PathVariable(代码中接收注解)
    body @RequestBody(代码中接收注解)