集成 Spring Doc 接口文档和 knife4j-SpringBoot 2.7.2 实战基础

优雅哥 SpringBoot 2.7 实战基础 - 04 -集成 Spring Doc 接口文档和 knife4j

前面已经集成 MyBatis Plus、Druid 数据源，开发了 5 个接口。在测试这 5 个接口时使用了 HTTP Client 或 PostMan，无论是啥都比较麻烦：得自己写请求地址 URL、请求参数等，于是多年前就出现了 Swagger 这个玩意。Swagger 可以自动生成接口文档，还能很方便的测试各个接口。但不幸的是，MVN Repository 上面 Springfox Swagger2 的版本停止于 2020 年 7月，而写下这篇文章是 2022 年 8 月，已经两年过去没有动静了，与此同时，springdoc-openapi 悄然出现。

spring doc open api 支持 Open API 3、Swagger-ui等，可以很方便与 Spring Boot 整合，配置和使用与 Springfox Swagger2 类似。

1 集成 Spring Doc

1.1 添加依赖

springdoc-openapi 不是 Spring Framework 官方团队开发的，而是社区项目，没有包含在 spring-boot-dependencies 中。故需要先定义版本号：

<properties>
		....
    <springdoc-openapi-ui.version>1.6.9</springdoc-openapi-ui.version>
</properties>

添加依赖：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>${springdoc-openapi-ui.version}</version>
</dependency>

该依赖里面使用了 swagger-ui，以HTML形式展示文档。

1.2 编写配置类

其实配置类写不写都可以，如果不写配置类，就通过注解定义文档信息就可以。创建类：com.yygnb.demo.config.SpringDocConfig

package com.yygnb.demo.config;

import io.swagger.v3.oas.models.ExternalDocumentation;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SpringDocConfig {
   

    private String title = "Hero SpringBoot Demo";
    private String description = "Hero Demo for usage of Spring Boot";
    private String version = "v0.0.1";
    private String websiteName = "Hero Website";
    private String websiteUrl = "http://www.yygnb.com";

    @Bean
    public OpenAPI heroOpenAPI() {
   
        return new OpenAPI()
                .info(new Info().title(title)
                        .description(description)
                        .version(version))
                .externalDocs(new ExternalDocumentation().description(websiteName)