Spring Boot 集成 Swagger3

Swagger是一种开源的API文档工具，它可以自动生成RESTful API文档，让开发者可以更容易地理解和使用API。使用Swagger可以提高开发效率，减少文档编写的工作量，并降低开发者之间的沟通成本。Swagger可以生成各种不同类型的文档，包括HTML、PDF、JSON和XML等。将Swagger与Spring Boot结合使用可以更加方便地生成API文档，并提供实时的API测试功能。使用Swagger可以提高API的可读性和可维护性，使API更易于开发人员和用户使用。

引入依赖

Swagger3 中，我们不需要再引入两个不同的依赖了，我们只需要引入一个依赖就足够，具体引入的依赖如下：

<dependency><groupId>io.springfox</groupId><artifactId>springfox-boot-starter</artifactId><version>3.0.0</version>
</dependency>

构建 Swagger 配置类

推荐大家在项目配置文件 application.yml 中添加关于 Swagger 开关的配置，比如这里我添加的配置如下，true 则代表开启 Swagger，false 则表示关闭 Swagger。

spring:mvc:pathmatch:matching-strategy: ANT_PATH_MATCHER
swagger:enabled: true

配置完成之后，我们就需要在 Swagger 配置类中获取 Swagger 开关的值了，关于具体用法就可以看下边配置代码。

package com.cunyu.springbootswagger3demo.config;import org.springframework.beans.factory.annotation.Value;
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.oas.annotations.EnableOpenApi;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;import java.util.ArrayList;@Configuration
@EnableOpenApi
public class SwaggerConfig {/*** 用于读取配置文件 application.properties 中 swagger 属性是否开启*/@Value("${swagger.enabled}")Boolean swaggerEnabled;
@Bean
public Docket docket() {return new Docket(DocumentationType.OAS_30).apiInfo(apiInfo())// 是否开启swagger.enable(swaggerEnabled).select()// 过滤条件，扫描指定路径下的文件.apis(RequestHandlerSelectors.basePackage("com.buba.controller"))// 指定路径处理，PathSelectors.any()代表不过滤任何路径//.paths(PathSelectors.any()).build();
}private ApiInfo apiInfo() {/*作者信息*/Contact contact = new Contact("XX", "https://baidu.com", "XXX@qq.com");return new ApiInfo("Spring Boot 集成 Swagger3 测试","Spring Boot 集成 Swagger3 测试接口文档","v1.0","https://cunyu1943.github.io",contact,"Apache 2.0","http://www.apache.org/licenses/LICENSE-2.0",new ArrayList());}
}

编写实体类

完成上面的步骤之后，我们的 Swagger 就配置好了，接下来我们就添加一个接口来看看

这里我以一个用户类为实例，带有 name、age 两个属性，也就是本文一开始项目结构截图中 entity 包下的内容。

package com.cunyu.springbootswagger3demo.entity;import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;@Data
@AllArgsConstructor
@NoArgsConstructor
@ApiModel("用户实体类")
public class User {@ApiModelProperty(value = "姓名", required = true, example = "村雨遥")private String name;@ApiModelProperty(value = "年龄", required = true, example = "20")private Integer age;
}

这里写了两个接口，一个是直接传参，另一种是通过利用创建的 User 实体类来传输，也就是项目结构中 controller 包中的内容。

package com.cunyu.springbootswagger3demo.controller;import com.cunyu.springbootswagger3demo.entity.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;@Api(tags = "测试")
@RestController
@RequestMapping("/user")
public class UserController {@ApiOperation("测试接口1")@PostMapping("/show1")public String show1(@ApiParam(value = "姓名", required = true, example = "村雨遥") @RequestBody String name) {return "hello," + name + ",welcome to springboot swagger3！";}@ApiOperation("测试接口2")@PostMapping("/show2")public String show2(@ApiParam(value = "用户对象", required = true) @RequestBody User user) {return "hello," + user.getName() + ",welcome to springboot swagger3！";}
}

查看并测试接口

启动我们的项目，然后在浏览器中访问如下地址，就可以访问项目的接口文档了。

http://localhost:8080/swagger-ui/index.html

这里也要注意一点，Swagger2 中的接口访问地址是：

http://localhost:8080/swagger-ui.html

Swagger2 和 Swagger3 接口访问地址是不同的。

springboot（05）整合 Swagger3 生成 API 接口文档相关推荐

Spring Boot 使用 Swagger3 生成 API 接口文档
前言在之前的文章中,我们已经讲了如何利用 Spring Boot 来集成 Swagger2,详情可戳:Spring Boot 集成 Swagger2,构建强大的 API 文档.但其实 Swagger ...
开发日记-20190328 关键词利用eolinker一键快速生成API接口文档
今天感觉效率真的很低= =各个层面的,apk发布到现场发现出现了问题,所以一个下午都在忙着解决现场出现的问题,领导一直打电话询问进度,午觉也没有睡所以今天预计的很多计划都处于停滞状态,像昨天规划的今天 ...
python生成api文档_Django 自动生成api接口文档教程
最近在写测试平台,需要实现一个节点服务器的api,正好在用django,准备使用djangorestframework插件实现. 需求实现一个接口,在调用时,通过传递的参数,直接运行对应项目的自动化 ...
python api接口生成_Django 自动生成api接口文档教程
最近在写测试平台,需要实现一个节点服务器的api,正好在用django,准备使用djangorestframework插件实现. 需求实现一个接口,在调用时,通过传递的参数,直接运行对应项目的自动化 ...
apidoc 自动化生成 api接口文档
手写api接口太麻烦. 学习了apidoc自动生成接口文档,这边做一下整理要用组件那就必须先安装 apidoc,做一下全局安装 npm install apidoc -g 新建配置文件apidoc. ...
Laravel使用swagger PHP生成api接口文档
Laravel使用swagger PHP生成api接口文档 Swagger集接口文档和测试于一体,就类比将postman和showdoc的结合体首先要先安装基于laravel5的swagger包地 ...
Laravel使用Apidoc注解自动生成Api接口文档
本教程从零开始搭建laravel项目,并安装Apidoc扩展及使用注解生成Api接口文档的教程,该扩展支持多应用/版本.Markdown文档.在线接口调试.接口生成器.代码模板生成器.Mock调试数 ...
如何自动生成 API 接口文档 - 一份详细指南
本篇文章详细教你如何使用 Apifox 的 IDEA 插件实现自动生成接口代码.好处简单总结有以下几点: 自动生成接口文档: 不用手写,一键点击就可以自动生成文档,当有更新时,点击一下就可以自动同步接 ...
项目配置Swagger2生成API接口文档
一.Swagger2介绍前后端分离开发模式中,api文档是最好的沟通方式. Swagger 是一个规范和完整的框架,用于生成.描述.调用和可视化 RESTful 风格的 Web 服务. 及时性 (接 ...

springboot（05）整合 Swagger3 生成 API 接口文档