IDEA+SpringBoot整合Swagger2实现自动创建API接口文档详解

一、传统维护API文档缺点

当下很多公司都采取前后端分离的开发模式，前端和后端的工作由不同的开发人员完成。在这种开发模式下，维护一份及时更新且完整的REST API文档将会极大的提高我们的工作效率。传统意义上的文档都是后端开发人员手动编写的，相信大家也都知道这种方式很难保证文档的及时性，长期以往这种文档也就会失去其参考意义，反而还会加大前后端之间的沟通成本，严重影响开发效率，更有甚者，由于沟通不畅导致业务上的漏洞，其危害与严重性可想而知。

二、Swagger2介绍

wagger2 的出现就是为了从根本上解决传统人工维护API文档的缺点。它作为一个规范和完整的框架，可以用于生成、描述、调用和可视化 RESTful 风格的 Web 服务：

• 接口文档在线自动生成，文档随接口变动实时更新，节省维护成本
• 支持在线接口测试，不依赖第三方工具

访问Swagger官网

三、IDEA+SpringBoot整合Swagger2

第一步：导入依赖

首先在SpringBoot项目的pom.xml中导入如下依赖：

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

第二步：创建Swagger配置类

我们可以在config目录下新建Swagger的配置类Swagger2Configuration.java，具体代码如下：

package com.panziye.demo.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
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;

/**
 * @author panziye
 * @version 1.0
 * @date 2021-08-02 13:53
 * @description <p></p>
 **/
@Configuration
@EnableSwagger2
public class Swagger2Configuration {

    /**
     * api接口包扫描路径
     */
    public static final String SWAGGER_SCAN_BASE_PACKAGE = "com.panziye.demo.controller";

    public static final String VERSION = "1.0.0";

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
            // 随便起
            .groupName("webApi")
            .apiInfo(webApiInfo())
            .select()
            .apis(RequestHandlerSelectors.basePackage(SWAGGER_SCAN_BASE_PACKAGE))
            // 可以根据url路径设置哪些请求加入文档，忽略哪些请求
            .paths(PathSelectors.any())
            .build();
    }

    private ApiInfo webApiInfo() {
        return new ApiInfoBuilder()
            //设置文档的标题
            .title("Swagger2测试案例")
            // 设置文档的描述
            .description("Swagger2测试案例 API 接口文档")
            // 设置文档的版本信息-> 1.0.0 Version information
            .version(VERSION)
            // 联系人和联系方式
            .contact(new Contact("panziye", "https://www.panziye.com", "1562691348@qq.com"))
            // 设置文档的License信息->1.3 License information
            .license("The Apache License")
            .licenseUrl("https://www.panziye.com")
            .build();
    }
}

Swagger2Configuration.java 配置类的内容不多，配置完成后也很少变化，简单了解即可。

第三步：API 接口编写

在完成了上述配置后，其实已经可以产生文档内容，但是这样的文档主要针对请求本身，而描述主要来源于函数等命名产生，对用户并不友好，我们通常需要自己增加一些说明来丰富文档内容。
潘老师在com.panziye.demo.controller包下新建了UserController用来测试，具体代码如下：

package com.panziye.demo.controller;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiResponse;
import io.swagger.annotations.ApiResponses;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

/**
 * @author panziye
 * @version 1.0
 * @date 2021-08-02 14:05
 * @description <p></p>
 **/

@RestController
@RequestMapping("/user")
@Api(tags = {"用户控制类"})
public class UserController {

    @PostMapping("/login")
    @ApiOperation(value = "登录接口")
    @ApiImplicitParams({
        @ApiImplicitParam(name = "username", value = "用户名", required = true, paramType = "query"),
        @ApiImplicitParam(name = "password", value = "密码", required = false, paramType = "query"),
    })
    @ApiResponses({
        @ApiResponse(code = 400, message = "请求参数没填好"),
        @ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对")
    })
    public String login(@RequestParam("username") String username, @RequestParam("password") String password) {
        return "success";
    }

    @PostMapping("/register")
    @ApiOperation(value = "注册接口")
    public String register(@RequestParam("username") String username,@RequestParam("password") String password) {
        return "success";
    }

    @GetMapping("/get/{id}")
    @ApiOperation(value = "根据id获取用户信息")
    public String getUser(@PathVariable("id")int id){
        return "success";
    }

}

本接口示例了 @ApiOperation 和 @ApiImplicitParam 两个注解的使用。Swagger 通过注解定制接口对外展示的信息，这些信息包括接口名、请求方法、参数、返回信息等。更多注解类型：

• @Api：修饰整个类，描述Controller的作用
• @ApiOperation：描述一个类的一个方法，或者说一个接口
• @ApiParam：单个参数描述
• @ApiModel：用对象来接收参数
• @ApiProperty：用对象接收参数时，描述对象的一个字段
• @ApiResponse：HTTP响应其中1个描述
• @ApiResponses：HTTP响应整体描述
• @ApiIgnore：使用该注解忽略这个API
• @ApiError ：发生错误返回的信息
• @ApiImplicitParam：描述一个请求参数，可以配置参数的中文含义，还可以给参数设置默认值
• @ApiImplicitParams：描述由多个 @ApiImplicitParam 注解的参数组成的请求参数列表

第四步：启动项目访问测试

我们期待SpringBoot项目，在浏览器访问http://localhost:8080/swagger-ui.html地址，发现如下：

注意：如果出现如下错误，请访问如下文章解决：

SpringBoot集成Swagger2报错Unable to infer base url. This is common…API Gateway

在使用IDEA+SpringBoot集成Swagger2时发现SpringBoot启动正常，没有报错，但当使用 […]

补充：在 Security 中的配置

如果你的Spring Boot 项目中如果集成了 Spring Security，在不做额外配置的情况下，Swagger2 文档会被拦截。解决方法是在 Security 的配置类中重写 configure 方法添加白名单即可：

@Override
public void configure ( WebSecurity web) throws Exception {
    web.ignoring()
      .antMatchers("/swagger-ui.html")
      .antMatchers("/v2/**")
      .antMatchers("/swagger-resources/**");
} 

OK，以上就是IDEA+SpringBoot整合Swagger2实现自动创建API接口文档详解内容。

喜欢 (4)赏

【请潘老师喝杯Coffee吧！】

分享 (0)