swagger3超详细教程

本文主要是介绍swagger3超详细教程，希望对大家解决编程问题提供一定的参考价值，需要的开发者们随着小编来一起学习吧！

自动化接口文档介绍

市面上有很多遵循 OpenApi 规范的自动化接口文档生成的解决方案。下面介绍两种：

ApiDoc
- 地址：https://apidocjs.com/
- github: https://github.com/apidoc/apidoc
- 简介：源代码中的注释直接自动生成api接口文档的工具
  - 在代码里面增加注释使用

/*** @apiGroup Product* @api {GET} /product/{id}  查询一个产品* @apiDescription 接口描述xxx* @apiParam {String} id 产品id(必填*)* @apiSuccessExample SuccessExample* HTTP/1.1 200* {* id: 'xxx',* name: 'xxx',* desc: 'xxxx'* }* @apiErrorExample ErrorExample*/@GetMapping("/{id}")public Product detail(@PathVariable String id){return JsonData.buildSuccess();}

优点
- 不入侵代码
- 支持跨语言使用
- 界面友好简洁
缺点
- 依赖环境 node/npm
Swagger 丝袜哥
- 地址：https://swagger.io/tools/swagger-ui/
- 简介：在java代码里面增加注解生成接口文档
  - 在代码里面增加注解

RestController
@RequestMapping("api/v1/user")
@Api(tags = "用户模块",value = "用户UserController")
public class UserController {@Autowiredprivate BannerService bannerService;@ApiOperation("分页用户列表")@GetMapping("list")public JsonData list(){List<BannerDO> list = bannerService.list();return JsonData.buildSuccess(list);}
}

优点
- 支持SpringMVC、SpringBoot、SpringCloud等主流java框架
- 对java代码友好
- 界面简洁
- 国内比较活跃,主要是spring社区带动
- 功能比较多
缺点
- 对跨语言支持不友好（可以和knife4j整合解决这个问题）
- 代码需要引入相关依赖包和配置
- 文档相对缺少

swagger介绍

Swagger介绍
- 基于 OpenAPI 规范（OpenAPI Specification，OAS）构建的开源接口文档自动生成工具，可以让开发人员快速设计、构建、记录以及使用 Rest API
- 版本的说明
  - 目前的版本有swagger2.0和3.0
    - swagger2于17年停止维护，现在最新的版本为17年发布的 Swagger3（Open Api3）。
  - Swagger 主要包含了以下三个部分：
    - Swagger Editor：基于浏览器的编辑器，我们可以使用它编写我们 OpenAPI 规范。
    - Swagger UI：它会将我们编写的 OpenAPI 规范呈现为交互式的 API 文档，后文我将使用浏览器来查看并且操作我们的 Rest API。
    - Swagger Codegen：它可以通过为 OpenAPI（以前称为 Swagger）规范定义的任何 API 生成服务器存根和客户端 SDK 来简化构建过程。
SpringFox介绍（是 spring 社区维护的一个非官方项目）
- 是一个开源的API Doc的框架，Marty Pitt编写了一个基于Spring的组件swagger-springmvc，用于将swagger集成到springmvc中来，它的前身是swagger-springmvc，可以将我们的Controller中的方法以文档的形式展现。官方定义为： Automated JSON API documentation for API’s built with Spring。
- 地址：https://github.com/springfox/springfox
- 版本的说明
  - SpringFox 3.0.0 发布（突破性的变更版本）
  - Spring5，Webflux支持，依赖少
  - 支持OpenApi 3.0.3
  - 有springboot的整合的starter，使用更便捷

springboot2.x整合swagger3

swagger2的整合和swagger3有一些区别。详细的可以查看以前的文档。

添加依赖

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

配置

# 应用名称
spring.application.name=shop# ===== 自定义swagger配置 ===== #
# 是否启用，测试和开发环境启用，生存环境关闭
swagger.enable=true
# 引用应用名称
swagger.application-name= ${spring.application.name}
#版本
swagger.application-version=1.0
#说明
swagger.application-description=shop api info

创建配置类

import io.swagger.annotations.ApiOperation;
import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.stereotype.Component;
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;@Component
@EnableOpenApi
@ConfigurationProperties("swagger")
@Data
public class SwaggerConfiguration {/*** 是否开启swagger，生产环境一般关闭，所以这里定义一个变量*/private Boolean enable;/*** 项目应用名*/private String applicationName;/*** 项目版本信息*/private String applicationVersion;/*** 项目描述信息*/private String applicationDescription;@Beanpublic Docket docket() {return new Docket(DocumentationType.OAS_30).pathMapping("/")// 定义是否开启swagger，false为关闭，可以通过变量控制，线上关闭.enable(enable)//配置api文档元信息.apiInfo(apiInfo())// 选择哪些接口作为swagger的doc发布.select()//apis() 控制哪些接口暴露给swagger，// RequestHandlerSelectors.any() 所有都暴露// RequestHandlerSelectors.basePackage("net.xdclass.*")  指定包位置// withMethodAnnotation(ApiOperation.class)标记有这个注解 ApiOperation.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)).paths(PathSelectors.any()).build();}private ApiInfo apiInfo() {return new ApiInfoBuilder().title(applicationName).description(applicationDescription).contact(new Contact("youyou", "https://baidu.com", "365414658@qq.com")).version(applicationVersion).build();}}

修改boot启动类
添加注解 @EnableWebMvc
注意：springboot-2.5.7以后的版本需要添加此注解
新版访问路径（和旧版的不一样）
http://localhost:8081/swagger-ui/index.html
注意：如果访问不成功，记得看是否有拦截器拦截了相关资源，配置不拦截即可

注解使用

用户模块相关接口文档配置
@Api 模块配置，用在controller类，描述API接口

    @Api(tags = "用户模块",value = "用户UserController")public class UserController {}

@ApiOperation 接口配置，用在方法上，描述接口方法

@ApiOperation("分页用户列表")@GetMapping("list")public JsonData list(){return JsonData.buildSuccess();}

@ApiParam 方法参数配置，用在入参上面，描述参数

@ApiOperation("用户登录")@PostMapping("login")public JsonData login(@ApiParam(name = "phone", value = "手机号",example = "13888888888")@RequestParam("phone") String phone,@ApiParam(name = "pwd", value = "密码",example = "123456")@RequestParam("pwd")String pwd){return JsonData.buildSuccess();}

restful例子

@ApiOperation("删除用户")@DeleteMapping("/delete/{id}")public JsonData  deleteById(@PathVariable int id) {return JsonData.buildSuccess();}

@ApiIgnore 忽略此接口不生成文档

@ApiIgnore@ApiOperation("删除用户")@DeleteMapping("/delete/{id}")public JsonData  deleteById(@PathVariable int id) {return JsonData.buildSuccess();}

@ApiModel()
- 用于类表示对类进行说明，用于参数用实体类接收，value–表示对象名，description–描述
- 这种一般用在post创建的时候，使用对象提交这样的场景
@ApiModelProperty()
- 用于方法，字段；表示对model属性的说明或者数据操作更改
- value–字段说明
- name–重写属性名字
- dataType–重写属性类型
- required–是否必填
- example–举例说明
- hidden–隐藏

@Data
@ApiModel("用户基本信息")
public class SaveUserRequest {private int age;private String pwd;@ApiModelProperty(value ="【必填】邮箱",required = true)private String email;@ApiModelProperty("【必填】手机号")private String phone;@ApiModelProperty(value="创建时间")private Date createTime;}