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

原创

已于 2022-08-08 16:44:31 修改 · 2.3k 阅读

12 ·

CC 4.0 BY-SA版权

文章标签：

#spring boot #spring #java #后端

于 2022-08-08 16:42:01 首次发布

本文介绍了如何在 SpringBoot 2.7 项目中集成 Spring Doc 和 Knife4j，通过详细步骤展示了添加依赖、编写配置类、配置YML文件、添加注解等过程，以及自定义配置和接口文档的使用。同时，文章提到了 Springfox Swagger2 的停滞和 Spring Doc 的优势，以及 Knife4j UI 的界面风格。

优雅哥 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)