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

Java技术 潘老师 3年前 (2021-08-02) 1414 ℃ (0) 扫码查看

一、传统维护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 配置类的内容不多,配置完成后也很少变化,简单了解即可。

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

第三步: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地址,发现如下:
IDEA+SpringBoot整合Swagger2实现自动创建API接口文档详解

IDEA+SpringBoot整合Swagger2实现自动创建API接口文档详解
注意:如果出现如下错误,请访问如下文章解决:
IDEA+SpringBoot整合Swagger2实现自动创建API接口文档详解

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


版权声明:本站文章,如无说明,均为本站原创,转载请注明文章来源。如有侵权,请联系博主删除。
本文链接:https://www.panziye.com/java/3393.html
喜欢 (4)
请潘老师喝杯Coffee吧!】
分享 (0)
用户头像
发表我的评论
取消评论
表情 贴图 签到 代码

Hi,您需要填写昵称和邮箱!

  • 昵称【必填】
  • 邮箱【必填】
  • 网址【可选】