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

IT 文章4年前 (2021)发布小编

一、传统维护API文档缺点

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

二、Swagger2介绍

wagger2 的出现就是为了从根本上解决传统人工维护API文档的缺点。它作为一个规范和完整的框架，可以用于生成、描述、调用和可视化 RESTful 风格的 Web 服务：
[list]接口文档在线自动生成，文档随接口变动实时更新，节省维护成本
支持在线接口测试，不依赖第三方工具[/list]
[dm href=’https://swagger.io/’]访问Swagger官网[/dm]

三、IDEA+SpringBoot整合Swagger2

第一步：导入依赖

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

程序员导航

优网导航旗下整合全网优质开发资源，一站式IT编程学习与工具大全网站

立即访问


	io.springfox
	springfox-swagger-ui
	2.9.2


	io.springfox
	springfox-swagger2
	2.9.2

第二步：创建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 
 **/
@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 配置类的内容不多，配置完成后也很少变化，简单了解即可。

[v_blue]如上代码所示，通过 @Configuration 注解，让 Spring 加载该配置类。再通过 @EnableSwagger2 注解来启用Swagger2。成员方法 createRestApi 函数创建 Docket 的Bean之后，webApiInfo() 用来创建该 Api 的基本信息（这些基本信息会展现在文档页面中）。select() 函数返回一个 ApiSelectorBuilder实例用来控制哪些接口暴露给 Swagger 来展现，本例采用指定扫描的包路径来定义，Swagger 会扫描该包下所有 Controller 定义的 API，并产生文档内容（除了被 @ApiIgnore 指定的请求）。[/v_blue]

AI 工具导航

优网导航旗下AI工具导航，精选全球千款优质 AI 工具集

立即访问

第三步：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 
 **/

@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 通过注解定制接口对外展示的信息，这些信息包括接口名、请求方法、参数、返回信息等。更多注解类型：
[list]@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述
@ApiModel：用对象来接收参数
@ApiProperty：用对象接收参数时，描述对象的一个字段
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiIgnore：使用该注解忽略这个API
@ApiError ：发生错误返回的信息
@ApiImplicitParam：描述一个请求参数，可以配置参数的中文含义，还可以给参数设置默认值
@ApiImplicitParams：描述由多个 @ApiImplicitParam 注解的参数组成的请求参数列表[/list]

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

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

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

[neilian ids=3397]

补充：在 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接口文档详解内容。