Swagger2接口文档基础使用方法

Swagger2

一、简介

Swagger接口文档是前后端分离时常用的工具，从接口文档上可以直接发送请求测试接口，其有如下优势：

1.Api文档与API定义同步更新

2.直接运行，可以在线测试API接口

3.支持多种语言

官网 ： https://swagger.io/

二、Swagger2配置

2.1 需要引入的依赖

</dependency>
<!--swagger2 依赖-->
<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger2</artifactId>
  <version>2.7.0</version>
</dependency>
<!-- swagger2 ui依赖 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.7.0</version>
</dependency>

当然还可以引入其他作者编写的第三方UI界面

<!--Swagger第三方UI依赖-->
<dependency>
  <groupId>com.github.xiaoymin</groupId>
  <artifactId>swagger-bootstrap-ui</artifactId>
  <version>1.9.6</version>
</dependency>

2.2 配置类注解

@Configuration
@EnableSwagger2
public class Swagger2Config {
    
    
  
}

2.3 配置Docket实例

@Bean
public Docket  createRestApi(){
    
    
    return new Docket(DocumentationType.SWAGGER_2);
}

2.4配置swagger apiInfo

private ApiInfo apiInfo(){
    
    
    return new ApiInfoBuilder()
            .title("云E办接口文档")
      			.description("接口文档")
            .contact(new Contact("sdh",
                                 "https://xxxxxxx.github.io/",
                                 "[email protected]"))
            .version("1.0")
            .build();
}

其中title是文档名称

description是文档描述

contact是作者信息

version是版本

2.5 Swagger配置扫描接口

@Bean
public Docket  createRestApi(){
    
    
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
          	.apis(RequestHandlerSelectors.
         		 			basePackage("com.xxx.server.controller"))
            .paths(PathSelectors.any())
            .build();
}

其中apiInfo()传入我们刚刚写好的apiInfo,之后再.select开始配置扫描接口，此处采用了建造者模式，在.selcet后只有.apis、.paths、.build三个选项。

(1) .apis

.apis(RequestHandlerSelectors.basePackage())

basePackage()表示基于包扫描，例如下面的例子

.apis(RequestHandlerSelectors.basePackage("com.sundaohan.server.controller"))

any()表示搜索全部

.apis(RequestHandlerSelectors.any())

none()表示都不扫描

.apis(RequestHandlerSelectors.none())

withClassAnnatation()表示按类上的注解扫描，需要传入一个注解的反射对象

.apis(RequestHandlerSelectors.withMethodAnnotation())

例如想扫描RestController注解修饰的类

.apis(RequestHandlerSelectors.withMethodAnnotation(RestController.class))

withMethodAnnotation()表示按方法上的注解扫描，需要传入一个注解的反射对象

.apis(RequestHandlerSelectors.withMethodAnnotation())

例如想扫描GetMapping修饰的方法

.apis(RequestHandlerSelectors.withMethodAnnotation(GetMapping.class))

(2) .paths

.paths()用来过滤路径，表示扫描什么路径下的内容

.any()表示扫描全部路径下的内容

.paths(PathSelectors.any())

.none()表示全都不扫描

.paths(PathSelectors.none())

.ant()表示扫描带有指定路径的接口，如

.paths(PathSelectors.ant("/api/**"))

表示只扫描请求以/api开头的接口，其他的不会扫描

(3).enable()

控制swagger是否开启，需要传入一个布尔值作为参数，默认为true，即开启状态

如果想要关闭，传入false即可

.enable(false)

设置完成后，访问localhost:端口号/doc.html就可以看到接口文档界面了