项目引入Swagger及使用姿势

1.导入pom依赖

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
     <groupId>com.github.xiaoymin</groupId>
     <artifactId>knife4j-spring-boot-starter</artifactId>
     <version>2.0.2</version>
</dependency>

2.添加swagger配置类

package com.demo.config;

import com.github.xiaoymin.swaggerbootstrapui.annotations.EnableSwaggerBootstrapUI;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
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;

import java.util.HashSet;

/**
 * <p>
 * swagger页面展示的配置
 * </p>
 *
 * @author Toby
 * @since 2020/5/13
 */
@Configuration
@EnableSwagger2
@EnableKnife4j
public class Swagger2Configuration {

    @Bean
    public Docket createRestApi() {
        HashSet<String> contentType = new HashSet<>(1);
        contentType.add("application/json");
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .consumes(contentType)
                .produces(contentType)
                .select()
            	// 扫描包路径
                .apis(RequestHandlerSelectors.basePackage("com.demo.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("xxx-api文档")
                .description("xxx-xx模块api文档")
                .version("1.0")
                .contact(new Contact("xxx项目组","","xxxx@xxx.com"))
                .build();
    }
    

}

注：basePackage要改为项目对应的controller目录路径，使用增强功能的话，需要在配置类上加@EnableKnife4j注解，并且在UI界面的个性化设置中开启增强功能。具体增强功能请移步至最后自行查看文档。

3.查看UI界面

启动项目后，在浏览器输入http://${host}??{port}/doc.html

4.项目中可能会用到的增强功能

• 自定义文档

  在resource目录下新建markdown文件夹，在目录下新建.md结尾的file即可。在application.yml中加入以下配置

  knife4j:
    markdowns: classpath:markdown/*
  

  注意：自定义文档说明必须以.md结尾的文件,其他格式文件会被忽略

• 访问权限控制-生产环境屏蔽Swagger所有资源接口

  之前的项目如果想在正式环境配置中屏蔽Swagger资源的话，是取的spring.profiles.active运行环境作判断，现在只需要在正式的application.yml中加入以下配置即可。

  knife4j:
    production: true
  

• 访问页面加权控制

  登录需要账号密码，提供简单的basic认证功能，在application.yml中加入以下配置即可。

  knife4j:
    ## 开启Swagger的Basic认证功能,默认是false
    basic:
      enable: true
    ## Basic认证用户名
      username: admin
    ## Basic认证密码
      password: 123456
  

4.注意事项

• 依赖变更

  ui前端界面显示的依赖更改，com.github.xiaoymin下的springfox-swagger-ui最终版本为1.9.6，之后版本包名更改为knife4j，不同框架集成方式的pom依赖自行查看原文文档。

• api分组相关，Docket实例不能延迟加载（目前应该用不到，具体多少个算多也不清楚，知道即可。）

  springfox默认会把所有api分成一组，这样访问时会在同一个页面里加载所有api列表。这样，如果系统稍大一点，api稍微多一点，页面就会出现假死的情况，所以很有必要对api进行分组。api分组，定义多个RestApi即可，通过groupName作区分。

5.文档地址

knife4j使用教程：https://doc.xiaominfo.com/knife4j/

GitHub地址：https://github.com/xiaoymin/swagger-bootstrap-ui

原文：https://www.cnblogs.com/tobyhomels/p/12890521.html