Swagger

Swagger 可以根据注释生成API文档。在 swagger-ui 生成的文档界面中，还可以直接访问这些接口来测试功能。

# 快速开始

# 1. Maven 配置

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

1
2
3
4
5
6
7
8
9
10
11
12

# 2. SB配置

@Configuration
@EnableSwagger // 开启 Swagger
class SwaggerConfig {

}

1
2
3
4
5

# 3. 启动SpringBoot并，访问

http://ip:port/swagger-ui.html

如果无法启动，报错 Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException,有两种方案解决:

降低 SB 版本, 如 2.2.6
配置文件 application.yml 修改SB路径匹配规则:

spring.mvc.pathmatch.matching-strategy: ANT_PATH_MATCHER

# SB配置详解

# 1、头部信息配置

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger
class SwaggerConfig {
    @Bean
    public Docket docket() {
        return new Docket(DocumentionType.SWAGGER_2).apiInfo(apiInfo());
    }
    
    private ApiInfo apiInfo() {
        Contact contact = new Contact("name", "url", "email");
        return new ApiInfo("Title", "Description", "version", "serviceUrl", contact, "license", "licenseURL", new ArrayList());
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

# 2、扫描接口配置

Docket.select().apis().paths().build();

@Bean
public Docket docket() {
    retrun new Docket().apiInfo(apiInfo())
        .select()
        /**
        *   RequestHandlerSelectors 配置要扫描的接口
        *   basePackage: 指定要扫描的包
        *   any(): 扫描全部
        *   none(): 全不扫描
        *   withClassAnnotation: 扫描类上的注解 ==> RequestHandlerSelectors.withClassAnnotation(RestController.class)
        *   withMethodAnnotation: 扫描方法上的注解 ==> RequestHandlerSelectors.withMethodAnnotation(GetMapping.class)
        **/
        .apis(RequestHandlerSelectors.basePacket("com.puhou"))
        /**
        *  Path：过滤路径
        *  ant:指定路径
        *  any:过滤全部
        *  none:全部不过滤
        *  regex:按照正则表达式来过滤
        */
        .paths(PathSelector.ant("/puhou/**")
        .build();
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

# 3、分组配置

@Bean
public Docket docketA() {
    return new Docket(DocumentationType.SWAGGER_2).groupName("A");
}

@Bean
public Docket docketB() {
    retrun new Docket(DocumentationType.SWAGGER_2).groupName("B");
}

1
2
3
4
5
6
7
8
9

可以通过分组配置和扫描接口配置来实现将不同包下的接口分配到不同的分组下。

 @Bean
 public Docket docket() {
    return new Docket(DocumentationType.SWAGGER_2).globalOperationParameters(setHeaderToken());
 }
 private List<Parameter> setHeaderToken() {
        ParameterBuilder tokenPar = new ParameterBuilder();
        List<Parameter> pars = new ArrayList<>();
        tokenPar.name("token").description("token").modelRef(new ModelRef("string")).parameterType("header").required(false).build();
        ParameterBuilder tenantIdPar = new ParameterBuilder();
        tenantIdPar.name("tenantId").description("单位id").modelRef(new ModelRef("string")).parameterType("header").required(false).build();
        ParameterBuilder applicationIdPar = new ParameterBuilder();
        applicationIdPar.name("applicationId").description("应用id").modelRef(new ModelRef("string")).parameterType("header").required(false).build();
        pars.add(tokenPar.build());
        pars.add(tenantIdPar.build());
        pars.add(applicationIdPar.build());
        return pars;
    }

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# 注解详解

@Api 用在 Controller 类上,标注类的功能。 @Api(tags={"用户"})
@ApiOperation 用在 Controller 方法上，标注接口功能。 @ApiOperation(value="获得用户列表", note="注意事项")
@ApiModel 用在数据类上, 说明类的作用。
@ApiModelProperty 用在数据类型的属性上，说明属性的作用。
@ApiImplicitParams + @ApiImplicitParam 对 @RequestParam 或 @PathVariable 中的参数进行解释。

    @GetMapping("/username/{username}/password/{password}")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "username",value = "用户名",defaultValue = "admin",paramType = "query",dataType="String",required = true),
            @ApiImplicitParam(name = "password",value = "密码",defaultValue = "admin",paramType = "query",dataType="String",required = true)
    })
    public String hello(
            @PathVariable("username")String username,
            @PathVariable("password")String password) {
        return username.concat(password);
    }

1
2
3
4
5
6
7
8
9
10

← Mapstruct druid starter→