SwaggerUI

一、Swagger极致用法

1 编写SpringBoot项目

编写SpringBoot项目，项目中controller中包含一个Handler，测试项目，保证程序可以正确运行。

@RestController
@RequestMapping("/people")
public class DemoController {

    @RequestMapping("/getPeople")
    public People getPeople(Long id, String name){
        People peo = new People();
        peo.setId(id);
        peo.setName(name);
        peo.setAddress("海淀");
        return peo;
    }
}
12345678910111213

2 导入Spring-fox依赖

在项目的pom.xml中导入Spring-fox依赖。目前最新版本为2.9.2，所以导入的依赖也是这个版本。其中springfox-swagger2是核心内容的封装。springfox-swagger-ui是对swagger-ui的封装。

<dependency>
    <groupId>io.springfoxgroupId>
    <artifactId>springfox-swagger2artifactId>
    <version>2.9.2version>
dependency>
<dependency>
    <groupId>io.springfoxgroupId>
    <artifactId>springfox-swagger-uiartifactId>
    <version>2.9.2version>
dependency>

1234567891011

3 添加注解

在SpringBoot的启动类中添加@EnableSwagger2注解。
添加此注解后表示对当前项目中全部控制器进行扫描。应用Swagger2

@SpringBootApplication
@EnableSwagger2
public class MyApp {
    public static void main(String [] args){
        SpringApplication.run(MyApp.class,args);
    }
}
1234567

4 访问swagger-ui

启动项目后在浏览器中输入http://ip:port/swagger-ui.html即可以访问到swagger-ui页面，在页面中可以可视化的进行操作项目中所有接口。

二、 Swagger-UI使用

访问swagger-ui.html后可以在页面中看到所有需要生成接口文档的控制器名称。

每个控制器中间包含多所有控制器方法的各种访问方式。如果使用的是@RequestMapping进行映射，将显示下面的所有请求方式。如果使用@PostMapping将只有Post方式可以能访问，下面也就只显示Post的一个。

点击某个请求方式中try it out

会出现界面要求输入的值。输入完成后点击Execute按钮

下面会出现Request URL已经不同状态码相应回来的结果。

三、 Swagger配置

可以在项目中创建SwaggerConfig，进行配置文档内容。
com.java.config.SwaggerConfig

1 配置基本信息

Docket：摘要对象，通过对象配置描述文件的信息。
apiInfo:设置描述文件中info。参数类型ApiInfo
select():返回ApiSelectorBuilder对象，通过对象调用build()可以创建Docket对象
ApiInfoBuilder：ApiInfo构建器。

@Configuration
public class SwaggerConfig {
    @Bean
    public Docket getDocket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(swaggerDemoApiInfo())
                .select()
                .build();
    }
    private ApiInfo swaggerDemoApiInfo(){
        return new ApiInfoBuilder()
                .contact(new Contact("北京尚学堂", "http://www.bjsxt.com", "[email protected]"))
                //文档标题
                .title("这里是Swagger的标题")
                //文档描述
                .description("这里是Swagger的描述")
                //文档版本
                .version("1.0.0")
                .build();
    }
}
123456789101112131415161718192021

显示效果如下：

2 设置扫描的包

可以通过apis()方法设置哪个包中内容被扫描

@Bean
public Docket getDocket() {
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(getApiInfo())
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.bjsxt.controller"))
            .build();
}
12345678

3 自定义注解设置不需要生成接口文档的方法

3.1 自定义注解
注解名称随意。

@Target({ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface NotIncludeSwagger {
}
1234

3.2 添加规则
通过public ApiSelectorBuilder apis(Predicate selector)可以设置生成规则。
public static Predicate not(Predicate predicate) :表示不允许的条件。
withMethodAnnotation：表示此注解是方法级别注解。

@Bean
public Docket getDocket(){
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(swaggerDemoApiInfo())
            .select()
            .paths(allowPaths())
            .apis(not(withMethodAnnotation(NotIncludeSwagger.class)))
            .build();
}
123456789

3.3 添加NotIncludeSwagger注解
在不需要生成接口文档的方法上面添加@NotIncludeSwagger注解后，该方法将不会被Swagger进行生成在接口文档中。

@NotIncludeSwagger
@RequestMapping("/getPeople2")
public People getPeople2(Integer id, String name, String address){
    People peo = new People();
    peo.setId(id);
    peo.setName(name);
    peo.setAddress(address);
    return peo;
}
123456789

4 设置范围

通过public ApiSelectorBuilder paths(Predicate selector)可以设置满足什么样规则的url被生成接口文档。可以使用正则表达式进行匹配。
下面例子中表示只有以/demo/开头的url才能被swagger生成接口文档。
如何希望全部扫描可以使用paths(PathSelectors.any())

@Bean
public Docket getDocket(){
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(swaggerDemoApiInfo())
            .select()
            .paths(allowPaths())
            .build();
}
private Predicate<String> allowPaths(){
    return or(
            regex("/demo/.*")
    );
}
12345678910111213

四、 Swagger2常用注解

1 Api

@Api是类上注解。控制整个类生成接口信息的内容。
tags：类的名称。可以有多个值，多个值表示多个副本。
description:描述，已过时。

@RestController
@RequestMapping("/people")
@Api(tags = {"mydemo"},description = "描述")
public class DemoController {
1234

在swagger-ui.html中显示效果。

2 ApiOperation

@ApiOperation写在方法上，对方法进行总体描述
 value：接口描述
 notes：提示信息
代码示例：

@ApiOperation(value="接口描述",notes = "接口提示信息")
1

在swagger-ui中显示效果

3 ApiParam

@ApiParam写在方法参数前面。用于对参数进行描述或说明是否为必添项等说明。
name：参数名称
value：参数描述
required：是否是必须

public People getPeople(Integer id, @ApiParam(value="姓名",required = true) String name, String address)
1

swagger-ui显示效果如下：

4 ApiModel

@ApiModel是类上注解，主要应用Model，也就是说这个注解一般都是写在实体类上。
 value：名称
 description：描述
代码示例：

@ApiModel(value = "人类",description = "描述")
public class People {
12

swagger-ui.html效果展示

5 ApiModelProperty

@ApiModelProperty可以用在方法或属性上。用于当对象作为参数时定义这个字段的内容。
value：描述
name：重写属性名
required：是否是必须的
example：示例内容
hidden：是否隐藏。
代码示例：

@ApiModelProperty(value = "姓名",name = "name",required = true,example = "张三")
private String name;
12

swagger-ui.html效果展示

6 ApiIgnore

@ApiIgnore用于方法或类或参数上，表示这个方法或类被忽略。和之前讲解的自定义注解@NotIncludeSwagger效果类似。只是这个注解是Swagger内置的注解，而@NotIncludeSwagger是我们自定义的注解。

7 ApiImplicitParam

@ApiImplicitParam用在方法上，表示单独的请求参数，总体功能和@ApiParam类似。
name：属性名
value：描述
required：是否是必须的
paramType：属性类型
dataType：数据类型
代码示例：

@PostMapping("/getPeople")
@ApiImplicitParam(name = "address",value = "地址",required = true,paramType = "query",dataType = "string")
public People getPeople(Integer id, @ApiParam(value="姓名",required = true) String name, String address){
123

swagger-ui.html效果展示

如果希望在方法上配置多个参数时，使用@ApiImplicitParams进行配置。示例如下：

@ApiImplicitParams(value={@ApiImplicitParam(name="id",value = "编号",required = true),@ApiImplicitParam(name="name",value = "姓名",required = true)})
1