Swagger3.X 接口文档（一）

接口文档

   谁产生和维护

         接口开发人员，后端工程师

   谁使用

        1.前端工程师

        2.测试工程师

        3.产品经理

接口存在的问题

      接口文档不存在，靠抓包获取

      接口更换后不及时更新

      接口文档写错，注解写错

      自动生成文档工具在跨语言不兼容

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

网址：https://github.com/OAI/OpenAPI-Specification

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

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

2. info - 有关API的元数据

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

二、自动化接口文档生成解决方案介绍

1、ApiDoc

网址：https://apidocjs.com/

github: https://github.com/apidoc/apidoc

简介：源代码中的注释直接自动生成api接口文档的工具

在代码里面增加注释使用

优点

      不入侵代码

     支持跨语言使用

     界面友好简洁

缺点

     依赖环境 node/npm

2、Swagger 丝袜哥

网址：https://swagger.io/tools/swagger-ui/

简介：在java代码里面增加注解生成接口文档

      在代码里面增加注解

优点

• 支持SpringMVC、SpringBoot、SpringCloud等主流java框架
• 对java代码友好
• 界面简洁
• 国内比较活跃,主要是spring社区带动
• 功能比较多

缺点

• 对跨语言支持不友好（可以和knife4j整合解决这个问题）
• 代码需要引入相关依赖包和配置
• 文档相对缺少

 三、 SpringFox3.x和Swagger3.x介绍

1、Swagger介绍

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

版本的说明

      目前的版本有swagger2.0和3.0

      swagger2于17年停止维护，现在最新的版本为17年发布的 Swagger3（Open Api3）。

2、Swagger 主要包含了以下三个部分：

Swagger Editor：基于浏览器的编辑器，我们可以使用它编写我们 OpenAPI 规范。

Swagger UI：它会将我们编写的 OpenAPI 规范呈现为交互式的 API 文档，后文我将使用浏览器来查看并且操作我们的 Rest API。

Swagger Codegen：它可以通过为 OpenAPI（以前称为 Swagger）规范定义的任何 API 生成服务器存根和客户端 SDK 来简化构建过程。

3、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，使用更便捷

• 基于OpenAPi规范-新版SpringBoot2.x整合Swagger3.x

1. SpringBoot添加pom文件依赖

<!--接口文档自动生成-->
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-boot-starter</artifactId>
   <version>3.0.0</version>
</dependency>

1. 配置文件增加配置-application.xml

#spring.application.name=shop接口,增加中文会乱码，可以修改文件编码，或者使用yml格式
spring.application.name=shop
# ===== 自定义swagger配置 ===== #
swagger.enable=true
swagger.application-name= ${spring.application.name}
swagger.application-version=1.0
#swagger.application-description=shop管理后端接口文档
swagger.application-description=shop api info

      3.创建配置类

package net.hlx.shop0907.config;

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;

/**
 * @ClassName: SwaggerConfiguration
 * @Description: TODO
 * @Author: HLX
 * @date: 2021/9/9 15:19
 * @Version: V1.0
 */
@Component  //组件
@Data   //lombok
@ConfigurationProperties("swagger")  //配置swagger.enable的前缀
@EnableOpenApi   //启动OpenApi
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("测试swagger", "https://www.baidu.com", "444012836@qq.com"))
                .version(applicationVersion)
                .build();
    }

1. 运行  http://localhost:8081/swagger-ui/index.html

     

新版访问路径（和旧版的不一样）

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

注意：如果访问不成功，记得看是否有拦截器拦截了相关资源，配置不拦截即可

五、掌握Swagger3.x常用注解讲解和配置

用户模块相关接口文档配置

    @Api 模块配置，用在controller类，描述API接口

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

@ApiOperation("图片管理列表") //必须加入哦！
@GetMapping("list")
public JsonData list() {
    //调用方法
    List<BannerDO> list = bannerService.list();
    //返回json
    return JsonData.buildSuccess(list);
}

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

@ApiOperation("用户登录")
@PostMapping("find")
public JsonData login(
        @ApiParam(name = "name", value = "用户名", example = "mike") @RequestParam("name") String name,
        @ApiParam(name = "phone", value = "手机号", example = "110") @RequestParam("phone") String phone
        ) {
    //返回数据
    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();
}

 运行效果：