6.3 使用 Swagger 生成 Web API 文档

水深无声 2023-10-08 17:54 6阅读 0赞

> ## 第6章 构建 RESTful 服务 ##
> 
> 6.1 [RESTful 简介][RESTful]  
> 6.2 [构建 RESTful 应用接口][RESTful 1]  
> 6.3 [使用 Swagger 生成 Web API 文档][Swagger _ Web API]  
> 6.4 实战：实现 Web API 版本控制

### 6.3 使用 Swagger 生成 Web API 文档 ###

高质量的 API 文档在系统开发的过程中非常重要。本节介绍什么是 Swagger， 如何在 Spring Boot 项目中集成 Swagger 构建 RESTful API 文档，以及为 Swagger 配置 Token 等通用参数。

#### 6.3.1 什么是 Swagger ####

> Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务，是非常流行的 API 表达工具。

普通的API文档存在的问题：

1.  由于接口众多，并且细节复杂（需要考虑不同的 HTTP 请求类型、HTTP 头部信息、HTTP 请求内容等），创建这样一份高质量的文档是一件非常繁琐的工作。
2.  随着需求的不断变化，接口文档必须同步修改，就很容易出现文档和业务不一致的情况。

为了解决这些问题，Swagger 应运而生，它能够自动生成完善的 RESTful API 文档，并根据后台代码的修改同步更新。这样既可以减少维护接口文档的工作量，又能将说明内容集成到实现代码中，让维护文档和修改代码合为一体，实现代码逻辑与说明文档的同步更新。另外，Swagger 也提供了完整的测试页面来测试 API，让 API 测试变得轻松、简单。

#### 6.3.2 使用 Swagger 生成 Web API 文档 ####

##### 1、配置 Swagger 的依赖。 #####

在pom.xml 文件中引入 Swagger 相关依赖包：`springfox-swagger2`、`springfox-swagger-ui`。如下：

pom.xml

<dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger2</artifactId>
                <version>2.8.0</version>
            </dependency>
            <dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger-ui</artifactId>
                <version>2.8.0</version>
            </dependency>

##### 2、创建 Swagger2 配置类。 #####

Swagger2Config.java

package com.example.restfulproject.comm.config;
    
    import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
    import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
    import springfox.documentation.builders.ApiInfoBuilder;
    import springfox.documentation.builders.PathSelectors;
    import springfox.documentation.builders.RequestHandlerSelectors;
    import springfox.documentation.service.ApiInfo;
    import springfox.documentation.spi.DocumentationType;
    import springfox.documentation.spring.web.plugins.Docket;
    import springfox.documentation.swagger2.annotations.EnableSwagger2;
    
    /**
     * Swagger2 配置类
     */
    @Configuration
    @EnableSwagger2
    public class Swagger2Config implements WebMvcConfigurer {
       
        
        @Bean
        public Docket

[RESTful]: https://blog.csdn.net/Shipley_Leo/article/details/129090115
[RESTful 1]: https://blog.csdn.net/Shipley_Leo/article/details/129093550
[Swagger _ Web API]: https://blog.csdn.net/Shipley_Leo/article/details/129110193