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 {
    @Autowired
    private 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;


    @Bean
    public 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", "[email protected]"))
                .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;

}