SpringBoot3整合SpringDoc实现在线接口文档

最新推荐文章于 2024-08-14 11:01:15 发布

Ρause

最新推荐文章于 2024-08-14 11:01:15 发布

阅读量1.1k

点赞数 17

文章标签： spring

本文链接：https://blog.csdn.net/qq_44624290/article/details/139889774

版权

写在前面

在现目前项目开发中，一般都是前后端分离项目。~~前端小姐姐负责开发前端，苦逼的我们负责后端开发~~

事实是一个人全干，在这过程中编写接口文档就显得尤为重要了。然而作为一个程序员，最怕的莫过于自己写文档和别人不写文档

大家都不想写文档，那这活就交给今天的主角Swagger来实现了

一、专业名词介绍

①OpenApi是什么？

解答：OpenApi是一个用于描述、定义和共享 RESTful API 文档的规范。最新规范是 OpenAPI 3.0

② Swagger是什么？

解答： Swagger 是一个用于设计和测试 RESTful APIs 的工具。

它提供了API 描述、请求和响应示例、API 测试和文档生成等丰富的功能。最新版本是Swagger3,支持OpenAPI3.0规范

③ SpringFox 是什么？

SpringFox 是 Spring 社区维护的一个项目（非官方），帮助使用者将 Swagger 2 集成到 Spring 中。

目前国内项目使用的都是它

github地址：https://github.com/springfox/springfox

④springDoc是什么？

解答： Spring-doc也是 Spring 社区维护的一个项目（非官方），帮助使用者将 Swagger 3 集成到 Spring 中

SpringDoc 支持 Swagger 页面 Oauth2 登录，相较于 SpringFox 而言，它的支撑时间更长，无疑是更好的选择。

但是在国内发展较慢，网上一找资料，出来的基本上是 Swagger2的内容。

地址：https://springdoc.org/

⑤ OpenAPI 、Spring-doc和 Swagger 之间的关系

解答：OpenAPI 定义了一种标准的格式来表示 API 文档，而 Swagger 是一个实现 OpenAPI 规范的工具

二、Swagger详细简介

Swagger 江湖人称“丝袜哥”，是一个帮助程序员生成接口文档的利器。

只需要简单配置，就可以生成带有漂亮UI界面的接口文档，而且编写的接口代码变了

接口文档随之也跟着变，做到了真正的解放双手。

官网https://swagger.io/

Swagger 优点

号称世界上最流行的API框架
Restful Api 文档在线自动生成器
直接运行，支持在线测试API
不仅仅支持Java，还支持多种语言（如：PHP、Python、Node.js等）

三、小试牛刀

说了这么多Swagger 的优点，接下来就小试牛刀，看看怎么将Swagger集成到SpringBoot中。

3.1、环境介绍

JDK：17
SpringBoot：3.3.0
Springdoc

注：细心的小伙伴可能已经发现了，在springboot3.0之前我用的都是Springfox来集成Swagger管理我们的API接口文档,

但是Springfox已经停止更新了，我们使用的是SpringBoot3 +jdk17 的环境后，Spring官网推荐了Springdoc 来整合swagger

3.2 新建一个springboot-web项目

3.3 添加依赖

由于篇幅原因，其他web项目相关依赖这里就不一一贴出来了。

第一个依赖是必须的，而且版本必须大于2.0.0

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.2.0</version>
</dependency>
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-api</artifactId>
    <version>2.2.0</version>
</dependency>

注：

我们这里使用的是jdk17+springboot3.3.0 环境，原来swagger的V2和V3都不能用了，小伙伴们一定更要注意这儿

不能引入的依赖

如果引入上面错误的依赖，项目启动会报下面错误，这时候我们引入上面正确的依赖重新启动项目即可

报错信息

3.4 编写`HelloController`

新建一个controller包—>建立一个HelloController类

新建Hellocontroller

@RestController
public class HelloController {

    @RequestMapping("/hello")
    public String hello(){
        return "hello";
    }
}

我们在浏览器中输入“http://localhost:8080/hello” 后回车，出现如下界面，说明我们的hello开发成功了

hello接口正常访问

3.5 访问swagger接口页面

注：我们这里采用的是openapi ,所以就不用像swagger的V2和v3那样添加配置类了

浏览器直接输入：http://localhost:8080/swagger-ui/index.html 回车即可看到下面界面

接口信息

整合swagger是不是很简单呢

四、修改接口

多种请求方式

从上面截图中我们看到，我们在HelloController 中只定义了一个接口，但是前端UI界面中出来个7种请求方式（GET、PUT、POST、DELETE、OPTIONS、HEAD、PATCH）的接口，这是为什么呢？

解答：@RequestMapping("/hello") 我们接口中只是指定了访问地址，并没有指定请求方式

我们将注解修改成@RequestMapping(path = "/hello",method = RequestMethod.GET)

或者@GetMapping("/hello") 然后重启服务，我们看到界面上就只有一种请求方式的接口了

get请求方式

五、接口文档常用配置

5.1 配置访问路径

在application.yml中可以自定义api-docs和swagger-ui的访问路径。当然了，如果没配置，默认就是下面路径

springdoc:
  api-docs:
    path: /v3/api-docs
  swagger-ui:
    path: /swagger-ui.html

5.2 配置接口文档基本信息

① 配置接口基本信息

新建一个config包—>并在包下建立一个SpringDocConfig配置类

新建配置类

② 配置接口文档基础信息

我们在配置类中添加如下代码，

@Configuration
public class SpringDocConfig {

    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
                // 配置接口文档基本信息
                .info(this.getApiInfo())
                ;
    }

    private Info getApiInfo() {
        return new Info()
                 // 配置文档标题
                .title("SpringBoot3集成Swagger3")
                // 配置文档描述
                .description("SpringBoot3集成Swagger3示例文档")
                // 配置作者信息
                .contact(new Contact().name("程序员小凡").url("https://www.xiezhrspace.cn").email("1666397814@163.com"))
                // 配置License许可证信息
                .license(new License().name("Apache 2.0").url("https://www.xiezhrspace.cn"))
                // 概述信息
                .summary("SpringBoot3集成Swagger3示例文档aaa")
                .termsOfService("https://www.xiezhrspace.cn")
                // 配置版本号
                .version("2.0");
    }

}

前端页面访问接口文档页面后显示如下

接口基本信息

② 配置接口servers信息

接口可能存在多环境，如开发环境、测试环境、生产环境等

我们可以通过@OpenAPIDefinition 配合servers 属性来配置不同环境，具体配置示例如下

@OpenAPIDefinition(
        servers = {
                @Server(description = "开发环境服务器", url = "http://localhost:8080"),
                @Server(description = "测试环境服务器", url = "https://test.xiezhr.com")
        }
)
@Configuration
public class SpringDocConfig {
    //...
}

配置完成后，浏览器访问显示如下

配置servers信息

③ 配置外部文档信息

有时候我们需要在在线接口文档中可以显示跳转到API的一些外部文档（比如项目部署文档等）

这个时候我们可以通过@OpenAPIDefinition 配合 externalDocs 属性来配置外部文档

具体配置如下

@OpenAPIDefinition(

    externalDocs = @ExternalDocumentation(
        description = "项目编译部署说明",
        url = "http://localhost:8080/deplay/readme.md"
    )
)
@Configuration
public class SpringDocConfig {
    //......
}

配置完后重启服务，浏览器访问接口文档，显示如下

外部API文档

SpringDocConfig 类完整配置代码如下

配置完上面信息后，重启服务，浏览器访问：http://localhost:8080/v3/swagger-ui/index.html

接口文档基本信息

5.3 配置扫描接口

应用场景：

有时候我们为了业务需要，我们建立了多个包下的接口，如admin包下的，common包下的接口，

为了安全起见，我们只允许接口文档中访问comm包下面的接口。

在不加任何配置的情况下，所以接口都会默认显示，具体如下

显示所有接口

配置扫描接口包：

在application.yml中可以自定义要扫描的接口包

springdoc:
  packages-to-scan: com.xiezhr.swaggerdemo.common.controller

配置好之后重启服务，我们发现前台UI只显示了common包下面的接口了

只显示common包下面的接口