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;}

这篇关于swagger3超详细教程的文章就介绍到这儿，希望我们推荐的文章对编程师们有所帮助！

---