乐趣区

关于springboot:Spring-Boot-集成-Swagger2构建强大的-API-文档

jiezi

前言

不论你是从事前端还是后端开发，置信都不免被接口文档折磨过。如果你是一个前端开发者，可能你会常常发现后端给的接口文档跟理论代码有所出入。而假如你是一个后端开发者，你可能又会感觉本人开发后端接口曾经够烦的了，还要破费大量精力去编写和保护接口文档，所以不免有时候会更新不及时。这就可能造成了前后端互相不了解，最初甚至吵起来，哈哈哈 🤪。

这时候咱们就会想，有没有一款工具，能让咱们疾速实现编写接口文档。这个工具既能保障咱们的接口文档实时更新，也能保障咱们不必花过多工夫去保护，就像写正文那么简略。

既然这是大多数前后端程序员的一大痛点，那必须得有一个解决方案吧。而这个计划应用的人多了，缓缓就成了一种标准，大家都默认应用这个计划，从而解决前后端接口文档不同步的问题，而这就是咱们明天的配角 – Swagger 的由来。

通过应用 Swagger，咱们只须要依照它所给定的一系列标准去定义接口以及接口的相干信息，而后它就能帮咱们主动生成各种格局的接口文档，不便前后端开发者进行前后端联调。同时，如果咱们的代码接口有所变动，只须要更新 Swagger 的形容，它就能进行实时更新，做到理论代码和接口文档的一致性。

Swagger 简介

Swagger 是什么

Swagger 是一种接口描述语言，次要用于生成、形容、调用以及可视化 RESTful 格调的 Web 服务接口文档。以前的我的项目可能更多的是前后端未离开同时进行开发，所以接口文档可能不是那么重要。但当初支流的我的项目根本都是前后端拆散，如果前后端没有沟通好，就有可能导致接口文档更新不及时，造成一些不必要的麻烦。而艰深地讲，Swagger 就是帮咱们写接口文档的。它不仅能主动生成实时接口文档，还能生成测试用例，不便咱们进行测试。

Swagger 次要提供了如下几种开源工具：

  1. Swagger Editor

Swagger 所提供的的编辑器，次要用于编辑 Swagger 形容文件，反对实时预览形容文件更新后的成果，相似于咱们的 Markdown 编辑器，右边编写源码，左边就能够进行实时预览。该编辑器不仅提供在线应用，还反对本地部署。

  1. Swagger UI

提供可视化的 UI 页面，用于展现 Swagger 的形容文件。接口的调用方、测试等都能够通过该页面查阅接口的相干信息，并且进行简略的接口申请测试。

  1. Swagger Codegen

通过应用该工具，能够将 Swagger 的形容文件生成 HTML 和 CWIKI 模式的接口文档，而且还能生成针对多种不同语言的服务端和客户端的代码。

Swagger UI

平时和咱们打交道最多的，可能就是 Swagger UI 这个工具了，它次要用于显示接口文档。依据咱们代码中依照 Swagger 标准所设置的形容，主动生成接口阐明文档。一个简略的示例如下：

Spring Boot 集成 Swagger

创立 Spring Boot 我的项目

通过以上对 Swagger 简略的介绍之后，咱们来看看如何在 Spring Boot 我的项目中应用 Swagger。

首先须要创立一个简略的 Spring Boot 我的项目，如果你还不晓得如何创立，能够参考我之前的一篇文章 创立 Spring Boot 我的项目的 3 种形式。

创立好之后的我的项目接口如下：

引入依赖

创立好 Spring Boot 我的项目之后，须要配置我的项目 pom.xml 文件，在其中引入 Swagger 的相干依赖。

<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>

构建 Swagger 配置类

引入依赖后，接下来就是构建 Swagger 的配置类了。

package com.cunyu.springbootswaggerdemo.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;

/**
 * Created with IntelliJ IDEA.
 *
 * @author : 村雨遥
 * @version : 1.0
 * @project : springboot-swagger-demo
 * @package : com.cunyu.springbootswaggerdemo.config
 * @className : Swagger2Configuration
 * @createTime : 2022/1/5 22:21
 * @email : 747731461@qq.com
 * @微信 : cunyu1024
 * @公众号 : 村雨遥
 * @网站 : https://cunyu1943.github.io
 * @description :
 */
@Configuration
@EnableSwagger2
public class Swagger2Configuration {

    /**
     * 配置 Swagger 2
     * 注册一个 Bean 属性
     * enable()：是否启用 Swagger，启用后能力在浏览器中进行拜访
     * groupName()：用于配置 API 文档的分组
     */
    @Bean
    public Docket docket() {return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(true)
                .groupName("v1")
                .select()
                // 过滤门路
                //.paths(PathSelectors.ant())
                // 指定扫描的包
                .apis(RequestHandlerSelectors.basePackage("com.cunyu.springbootswaggerdemo.controller"))
                .build();}

    private ApiInfo apiInfo() {
        /* 作者信息 */
        Contact contact = new Contact("村雨遥", "https://cunyu1943.github.io", "747731461@qq.com");
        return new ApiInfo(
                "Swagger 测试接口文档",
                "Spring Boot 集成 Swagger 测试接口文档",
                "v1.0",
                "https://cunyu1943.github.io",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}

编写接口

配置好 Swagger 后，在咱们的我的项目中增加一个简略的接口，这里以一个简略的有参和无参接口为例。

package com.cunyu.springbootswaggerdemo.controller;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * Created with IntelliJ IDEA.
 *
 * @author : 村雨遥
 * @version : 1.0
 * @project : springboot-swagger-demo
 * @package : com.cunyu.springbootswaggerdemo.controller
 * @className : SwaggerDemoController
 * @createTime : 2022/1/5 22:21
 * @email : 747731461@qq.com
 * @微信 : cunyu1024
 * @公众号 : 村雨遥
 * @网站 : https://cunyu1943.github.io
 * @description :
 */

@Api
@RestController
public class SwaggerDemoController {@ApiOperation(value = "hello world 接口")
    @GetMapping("hello")
    public String hello() {return "hello world";}

    @ApiOperation(value = "有参接口")
    @PostMapping("demo")
    public String demo(@ApiParam(name = "name", value = "村雨遥", required = true) String name) {return "hello," + name;}
}

查看并测试接口

实现上述步骤后，咱们启动我的项目，而后在浏览器中拜访如下地址，就能够拜访咱们我的项目的接口文档了。

http://localhost:8080/swagger…

拜访如上地址后，如果呈现上面的界面，阐明咱们 Spring Boot 集成 Swagger2 就到此胜利了。

点开具体的接口，就会有这个接口的一些详细信息，如下图所示，个别包含：

  1. 接口申请形式
  2. 接口申请门路及形容
  3. 接口申请参数
  4. 接口响应

如果咱们要进行简略的测试，则点击上图中右上方的 Try it out，而后咱们就能够编辑申请参数的值，编辑实现之后点击下方的 Execute 即可查看接口返回值。

以我给的接口为例，我传入了一个参数 name，而后执行 demo 接口，最初会给我返回 hello,name 的后果，其中 name 是我传入的参数值，这里我传入了村雨遥，所以后果应该会失去 hello, 村雨遥 ，能够看到 Swagger 测试中也给我返回了对应的后果，阐明咱们的接口测试胜利！

留神

如果在整合过程中呈现如下谬误：

org.springframework.context.ApplicationContextException:Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException

这里可能是因为 Spring Boot 版本过高导致，我写作本文时，一开始应用的 SpringBoot 2.6.2 版本，所以呈现了该谬误，而当我将 SpringBoot 降级为 2.5.6 时，该谬误就不再呈现。所以如果你也呈现了这个问题，也能够尝试升高 SpringBoot 版本来解决。

总结

以上就是本文的所有内容了，次要对 Swagger 进行了简略介绍，并用 Spring Boot 集成 Swagger，并进行简略的测试。而对于文章中的示例代码，我曾经上传到了 Github，如果有须要的敌人，能够自取。

传送门：https://github.com/cunyu1943/…

退出移动版