利用 Swagger 构建 Api 文档，提升你的对接效率

最新推荐文章于 2024-08-16 16:39:42 发布

平头哥的技术博文

最新推荐文章于 2024-08-16 16:39:42 发布

阅读量1.1k

点赞数 3

分类专栏： SpringBoot 学习笔记

本文链接：https://blog.csdn.net/z694644032/article/details/97954637

版权

本文介绍了如何利用 Swagger 在 Spring Boot 项目中构建 API 文档，提高对接效率。通过配置依赖、编写实体类和 API 文档，实现代码与文档的同步更新。同时，文章提到了 Swagger UI 的交互式特点，以及如何在生产环境中安全地使用 Swagger。最后，文章推荐了一个更符合国人审美的 Swagger 替代框架。

摘要由CSDN通过智能技术生成

前言

Swagger 是一套基于 OpenAPI 规范构建的开源工具，可以帮助我们设计、构建、记录以及使用 Rest API。越来越多的公司在项目中使用Swagger作为文档构建工具，Swagger主要有一下优点：

代码变，文档变。只需要少量的注解，Swagger 就可以根据代码自动生成 API 文档，很好的保证了文档的时效性
跨语言性，支持 40 多种语言
Swagger UI 呈现出来的是一份可交互式的 API 文档，我们可以直接在文档页面尝试 API 的调用，省去了准备复杂的调用参数的过程
还可以将文档规范导入相关的工具（例如 SoapUI）, 这些工具将会为我们自动地创建自动化测试

如果你还在手写Api文档，你可以尝试使用swagger去构建你的文档。你是否已经对 Swagger 产生了浓厚的兴趣了呢？下面我们就将一步一步地在 Spring Boot 项目中集成和使用 Swagger，让我们从准备一个 Spring Boot 的 Web 项目开始吧。

springboot 结合 swagger

1、在`pom.xml`中配置依赖

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

2、配置`swaggerconfig`信息

我们要使用swagger就需要编写一个swagger的配置文件，主要用来用来初始化swagger。配置信息如下：

@EnableSwagger2
@Configuration
//@Profile({"dev","test"})
@ConditionalOnProperty(name = "swagger.enable",havingValue = "true")
public class Swagger2Config {
   

    @Bean
    public Docket createRestApi() {
   
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                // 扫描的包
                .apis(RequestHandlerSelectors.basePackage("com.curry.springbootswagger.controller"))
                // 选择API路径
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
   
        return new ApiInfoBuilder()
                // swagger ui 的标题
                .title("Spring B