介绍

特点

• Restful APi 文档在线自动生成

• API文档与API定义同步更新

• 在线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.9.2</version>
</dependency>

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>2.0.9</version>
</dependency>

配置类

• Swagger2 使用 @EnableSwagger2

• knife4 使用 @EnableSwagger2WebMvc

@Configuration //配置类
@EnableSwagger2// 开启Swagger2的自动配置
public class SwaggerConfig {
    
}

@Configuration
//@EnableSwagger2
@EnableSwagger2WebMvc
public class SwaggerConfig {
    @Resource
    private OpenApiExtensionResolver openApiExtensionResolver;

    @Bean
    public Docket createRestApi() {
        //创建 docket对象
        Docket docket = new Docket(DocumentationType.SWAGGER_2);
        ApiInfoBuilder builder = new ApiInfoBuilder();
        builder.title("YOAS在线办公系统");
        ApiInfo info = builder.build();
        docket.apiInfo(info);

        //配置指定包下特定注解的方法加入swagger
        ApiSelectorBuilder selectorBuilder = docket.select();
        selectorBuilder.paths(PathSelectors.any());
        selectorBuilder.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class));
        //更新到 docket
        docket = selectorBuilder.build().extensions(openApiExtensionResolver.buildExtensions("v1"));

        //让 swagger 支持识别 JWT
        ApiKey apiKey = new ApiKey("token", "token", "header");
        List<ApiKey> apiKeyList = new ArrayList<>();
        //封装到 apiKeyList
        apiKeyList.add(apiKey);
        //更新到 docket
        docket.securitySchemes(apiKeyList);

        //设定令牌作用域+各种封装
        AuthorizationScope scope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] scopes = {scope};
        SecurityReference reference = new SecurityReference("token", scopes);
        List refList = new ArrayList();
        refList.add(reference);
        SecurityContext context = SecurityContext.builder().securityReferences(refList).build();
        List cxtList = new ArrayList();
        cxtList.add(context);
        docket.securityContexts(cxtList);

        return docket;
    }
}

• swagger 访问 .../swagger-ui.html

• knife5 访问 .../doc.html

Docket 实例配置

Swagger信息

@Bean
public Docket api() {
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo()) //Docket实例关联apiInfo()
}
  //配置SwaggerAPIInfo类
    private ApiInfo apiInfo() {
    return new ApiInfoBuilder()
            .title("接口文档") //标题
            .description("") //描述
            .version() //版本
            .termsOfServiceUrl("")  //组织的链接
            .build();
}

配置扫描接口

return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            .apis(RequestHandlerSelectors.any())
            .paths(PathSelectors.any())
            .build();
}

• apis ：配置具体扫描接口方式 ，定义在RequestHandlerSelectors
• 扫描指定的包下的接口：basePacket("xx")
• 扫描所有包：any()
• 根据注解扫描：参数是注解的类对象
• withClassAnnotation

withClassAnnotation(Controller.class)
//只扫描有controller注解的类中的接口

• withMethodAnnotation

withMethodAnnotation(GetMapping.class)
//只扫描get请求

• paths 对apis定义的接口扫描方式进行路径过滤，定义在 PathSelectors
• 扫描指定路径下的接口：ant(final String antPattern)
• 扫描任何路径 ：any()
• 正则匹配：regex(final String pathRegex)

配置开关swagger

• 通过enable()方法配置是否启用swagger
如果是false，swagger将不能在浏览器中访问了

return new Docket(DocumentationType.SWAGGER_2)
    .apiInfo(apiInfo())
    .enable(false)

• 动态配置根据项目启动环境spring.profiles.active=xxx是否开启

@Bean
public Docket docket(Environment environment) {
    // 设置要显示swagger的环境
    Profiles of = Profiles.of("dev", "test");
    // 判断当前是否处于该环境
    // 通过 enable() 接收此参数判断是否要显示
    boolean isOpen = environment.acceptsProfiles(of);

   return new Docket(DocumentationType.SWAGGER_2)
    .apiInfo(apiInfo())
    .enable(isOpen)
    ......
}

配置API分组

一个docket就是一个分组

return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
  .groupName("hello") // 配置分组

 @Bean
public Docket docket1() {
return new Docket(DocumentationType.SWAGGER_2).groupName("group1");
}
@Bean
public Docket docket2() {
return new Docket(DocumentationType.SWAGGER_2).groupName("group2");
}
@Bean
public Docket docket3() {
return new Docket(DocumentationType.SWAGGER_2).groupName("group3");
}

常用注解

接口类注解

实体类注解

@ApiModel("用户实体")
public class User {
    @ApiModelProperty("用户名")
    private String username;
    @ApiModelProperty("密码")
    private String password;
    //getter-setter
}