SpringBoot整合Swagger3.0接口文档提效神器详解

OpenApi规范

声明了用于文档规范的版本

地址：github.com/OAI/OpenAPI…

OpenApi介绍

OpenApi规范经过Reverb Technologies和SmartBear等公司多年的发展，OpenApi计划拥有该规范（捐赠之后），OpenAPI Initiative在GitHub上托管社区驱动的规范。

规范是一种与语言无关的格式，用于描述RestFul Web服务，应用程序可以解释生成的文件，这样才能生成代码、生成文档并根据其描述的服务创建模拟应用。

开放API规范（OAS）是一种无需编写实际API代码就可以记录API的方法。这是一种开放源代码格式，可以用来描述API。在此过程中，我们可以使用JSON或YAML格式

OpenAPI文档有三个必须的部分或对象，也可以增加其他模块：

1.openapi - OpenAPI规范版本的语义版本号

2.info - 有关API的元数据

3.paths - API的可用路径和操作

业界自动化接口文档生成的解决方案介绍

ApiDoc

地址：apidocjs.com/

github：github.com/apidoc/apid…

简介：源代码中的注释直接自动生成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

地址：swagger.io/tools/swagg…

简介：在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整合解决这个问题）

代码需要引入相关依赖包和配置

文档相对缺少

SpringFox3.X和Swagger3.X介绍

Swagger介绍

基于OpenAPI规范构建的开源接口文档自动生成工具,可以让开发人员快速设计、构建、记录以及使用RestAPI

版本说明

目前的版本有swagger2.0和3.0

swagger2于17年停止维护，现在最新的版本为17年发布的swagger3(OpenApi3)

Swagger主要包含以下三个部分

• SwaggerEditor：基于浏览器的编辑器，我们可以使用它来编写我们OpenAPI规范
• SwaggerUi：它会将我们编写的OpenAPI规范呈现为交互式的API文档
• SwaggerCodegen：它可以通过OpenAPI（以前称为Swagger）规范定义的任何API生成服务器存根和客户端SDK来简化构建过程

SpringFox介绍

（是spring社区维护的一个非官方项目）

是一个开源的API Doc的框架，Marty Pitt编写了一个基于Spring组件的Swagger-SpringMvc，用于将Swagger集成到Springmvc中来，它的前身是Swagger-Springmvc，可以将我们的Controller中的方法以文档的形式展现

地址：github.com/springfox/s…

版本说明

• SpringFox3.0.0（减少了Swagger2的一些配置）
• Spring5 Webflux支持，依赖少
• 支持OpenApi 3.0.3
• 有SpringBoot的整合的starter，使用更便捷

SpringBoot2.X整合Swagger3.0

Step1：pom添加依赖

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

Step2：配置文件

#spring.application.name=shop-managerp接口,增加中文会乱码，可以修改文件编码，或者使用yml格式
spring.application.name=shop-manager
# ===== 自定义swagger配置 ===== #
swagger.enable=true
swagger.application-name= ${spring.application.name}
#接口文档版本
swagger.application-version=1.0
#swagger.application-description=该接口文档的描述
swagger.application-description=1024shop api info 

Step3：配置类

@Component//Spring扫描
@EnableOpenApi//开启OpenApi规范
@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("com.keep.*")  指定包位置
        // 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("作者", "网站", "邮箱"))
                .version(applicationVersion)
                .build();
    }
}

🦂注意

http://localhost:端口/swagger-ui/index.html

如果启动后访问不成功，查看是否有拦截器拦截了相关资源配置，配置不拦截即可

Swagger3.X常用注解和配置

@Api

模块配置，用在Controller类上，描述Api接口

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

@ApiOperation

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

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

@ApiParam

方法参数配置，用在入参中或注解中

    @ApiOperation("用户登录")
    @GetMapping("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();
    }

或

    @RequestMapping(value = "/test",method = RequestMethod.GET)
    @ApiOperation(value = "文档描述")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "name1",value = "名称1",defaultValue = "空串",required = true,paramType = "query"),
            @ApiImplicitParam(name = "name2",value = "名称2",defaultValue = "空串",required = true,paramType = "query")
    })
    public String test(String name1,String name2) {
        //language=JSON
        String aa = "{\n  "name": "张三",\n  "age": 21\n}";
        return name1+name2;
    }
​

@Apilgnore

忽略此接口不生成文档

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

Swagger3.X对象注解ApiModel讲解

@ApiModel

用于类 表示对类进行说明，用于参数用实体类接收，value-表示对象名，description-描述

这种一般用在post创建的时候，使用对象提交这样的场景

@ApiModelProperty

用于方法，字段；标识对model属性的说明或者数据操作更改

value：字段说明

name：重写属性名字

dateType：重写属性类型

required：是否必填

example：举例说明

hidden：隐藏

🌰

@Api(tags = "用户模块",value = "用户Controller")
@RestController
@RequestMapping("api/v1/user")
@Slf4j
public class UserController {
​
    @ApiOperation("新增用户")
    @RequestMapping(value = "/saveUser",method = RequestMethod.POST)
    //public JsonData saveUser(@RequestBody UserParam userParam){ 用于发送json请求
    public JsonData saveUser(UserParam userParam){//用于表单请求
        log.info("UserController.saveUser 新增用户 Param:{}",userParam);
        return JsonData.buildError("新增成功");
    }
}

@ApiModel(value = "新增用户请求模型")
@Data
public class UserParam {
​
    @ApiModelProperty(value = "主键")
    private int id;
​
    @ApiModelProperty(value = "邮箱",required = true,example = "736317048@qq.com")
    private String email;
​
    @ApiModelProperty(value = "手机号",required = false)
    private String phone;
​
    @ApiModelProperty(value = "用户名称")
    private String name;
}

Swagger3.X响应结果ApiResponse

@ApiResponse

描述接口响应

🌰 注意要导Swagger3的包才能有以下属性

    @ApiOperation(value = "轮播图信息")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id",value = "主键id",defaultValue = "空串",required = true,paramType = "query")
    })
    @ApiResponses({
            @ApiResponse(responseCode = "401",description = "请进行身份验证"),
            @ApiResponse(responseCode = "403",description = "拒绝执行"),
            @ApiResponse(responseCode = "404",description = "资源未找到"),
            @ApiResponse(responseCode = "500",description = "系统异常")
    })
    @RequestMapping(value = "/getBannerById",method = RequestMethod.GET)
    public JsonData getBannerById(@RequestParam Long id){
        try {
            BannerDO bannerDO = bannerService.getBannerById(id);
            return JsonData.buildSuccess(bannerDO);
        }catch (Exception e){
            log.error("BannerController.getBannerById  Exception -> error:{}, param:{}",e,id);
        }
        return JsonData.buildError("查询失败",-1);
    }

感觉不错的大佬点个赞呗 演示不易