1. 概念

OpenAPI

是一个组织（OpenAPI Initiative），他们指定了一个如何描述HTTP API的规范（OpenAPI Specification）。既然是规范，那么谁想实现都可以，只要符合规范即可。

Swagger

它是SmartBear公司的一个开源项目，里面提供了一系列工具，包括著名的 swagger-ui。swagger是早于OpenApi的，某一天swagger将自己的API设计贡献给了OpenApi，然后由其标准化了。

Springfox

是Spring生态的一个开源库，是Swagger与OpenApi规范的具体实现。我们使用它就可以在spring中生成API文档。以前基本上是行业标准，目前最新版本可以支持 Swagger2, Swagger3 以及 OpenAPI3 三种格式。但是其从 2020年7月14号就不再更新了，不支持springboot3，所以业界都在不断的转向我们今天要谈论的另一个库Springdoc，新项目就不要用了。

Springdoc

算是后起之秀，带着继任Springfox的使命而来。其支持OpenApi3规范，支持Springboot3，我们的新项目都应该使用这个

下面介绍Springdoc的使用

2. 引入依赖

<dependency>
   <groupId>org.springdoc</groupId>
   <artifactId>springdoc-openapi-ui</artifactId>
   <version>1.7.0</version>
</dependency>

访问地址 http://server:port/context-path/swagger-ui.html

3. 配置文档信息

创建一个OpenAPI 的bean，配置文档名称等信息

import io.swagger.v3.oas.models.ExternalDocumentation;  
import io.swagger.v3.oas.models.OpenAPI;  
import io.swagger.v3.oas.models.info.Contact;  
import io.swagger.v3.oas.models.info.Info;  
import io.swagger.v3.oas.models.info.License;
@Configuration  
public class SpringDocConfig {  
    @Bean  
    public OpenAPI myOpenAPI() {  
        return new OpenAPI()  
                .info(new Info()  
                        .title("考试系统API")  
                        .version("v1.0.0")  
                        .license(new License()  
                                .name("许可协议")  
                                .url("https://github.com/"))  
                        .contact(new Contact()  
                                .name("Me")  
                                .email("007@gmail.com")))  
                .externalDocs(new ExternalDocumentation()  
                        .description("007的博客")  
                        .url("https://gitbub.com"));  
    }  
}

4. 配置文档分组

通常根据请求地址分组/api/teacher/、/api/user/

@Bean  
public GroupedOpenApi adminApi() {  
    return GroupedOpenApi.builder()  
            .group("question")  
            .pathsToMatch("/question/**")  
            .build();  
}

5. 常用注解

注解	含义
@Tag	用在controller类上，描述此controller的信息
@Operation	用在controller的方法里，描述此api的信息
@Parameter	用在controller方法里的参数上，描述参数信息
@Parameters	用在controller方法里的参数上，批量添加
@Schema	用于Entity，以及Entity的属性上
@ApiResponse	用在controller方法的返回值上
@ApiResponses	用在controller方法的返回值上
@Hidden	用在各种地方，用于隐藏其api

同时，Springdoc还支持 Java Bean Validation API 的注解，例如@NotNull 等

6. 认证授权

有时我们的服务需要认证，否则就调用不通，那怎么办

Springdoc 使用@SecurityScheme 来定义一个安全模式，我们可以定义全局的，也可以针对某个controller定义类级别的

7. knife4j

Knife4j是一个基于Swagger UI的增强版UI框架

Knife4j在OpenAPI3规范中，底层基础框架选择springdoc-openapi项目（所以引入knife4j后就不用再引入springdoc-openapi）

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

application.yml 配置

# knife4j的增强配置，不需要增强可以不配  
knife4j:  
  enable: false  # 是否启用knife4j增强,如果只是使用knife4j 的UI ,则可以关闭
  setting:  
    language: zh_cn

7.1. 访问地址

knife4j导出接口文档

http://127.0.0.1:8080/doc.html

knife4j UI界面

http://127.0.0.1:8080/doc.html

Swagger UI界面

http://127.0.0.1:8080/swagger-ui/index.html

Swagger接口文档工具