API接口框架-Swagger

1. Swagger简介

号称世界上最流行的API接口框架，可以在线生成restful风格的api文档并支持文档的同步更新，可以直接运用在线测试api接口。支持多语言。

在前后台分离开发的背景下诞生的。

https://www.swagger.io

2. OpenAPI 是什么?

Open API 即开放 API，也称开放平台。所谓的开放 API（OpenAPI）是服务型网站常见的一种应用，网站的服务商将自己的网站服务封装成一系列 API（Application Programming Interface，应用编程接口）开放出去，供第三方开发者使用，这种行为就叫做开放网站的 API，所开放的 API 就被称作 OpenAPI（开放 API ）。

Open API 规范可以使用YAML或者JSON格式进行编写。这样更利于我们和机器进行阅读。Open API规范为REST API定义了一个与语言无关的标准接口，允许人和计算机发现和理解服务的功能，无需访问源代码，文档或者通过流量检查。正确定义后消费者可以使用最少量的实现逻辑来理解远程服务并与之交互。

3. Swagger组件

Swagger是一个为围绕Open API规范构建的开源工具，可以帮助设计、构建、记录和使用REST API。

组件包括：

Swagger Editor：基于浏览器编辑器，可以在里面编写Open API规范。类似Markdown具有实时预览描述文件的功能。

Swagger UI：将Open API规范呈现为交互式API文档。用可视化UI展示描述文件。

Swagger Codegen：将OpenAPI规范生成为服务器存根和客户端库。通过Swagger Codegen可以将描述文件生成html格式和cwiki形式的接口文档，同事也可以生成多种语言的客户端和服务端代码。

Swagger Inspector：和Swagger UI有点类型，但是可以返回更多信息，也会保存请求的实际参数数据。

Swagger Hub：集成了上面所有的项目的各个功能，你可以以项目和版本为单位，将你的描述文件上传到Swagger Hub中。在Swagger Hub中可以完成上面项目的所有工作，需要注册账号，分免费版和收费版。

使用Swagger就是把相关的信息存储在它定义的描述文件里面（yml或json格式），再通过维护这个描述文件可以去更新接口文档，以及生成各端代码。

4. Springfox

Springfox 利用自身的AOP特性，把Swagger集成进来，底层还是Swagger。根据代码生成接口文档，所以正常的运行更新项目把那本，修改代码即可，而不需要跟着修改描述文件。我们在实际开发中都是直接使用springfox。

5.Knife4j简介

knife4j是为Java MVC框架集成Swagger 生成Api文档 的增强解决方案。官方网址

Knife4j的前身是swagger-bootstrap-ui,前身swagger-bootstrap-ui是一个纯swagger-ui的ui皮肤项目

6.Knife4j使用

6.1. 使用说明

为了使用knife4j，我们需要以下步骤：

引入相关依赖

在springboot启动类上添加swagger2\&knife4j注解，标注对哪些controller生成文档

在config目录下创建swagger配置类，设置knife4j的基本信息

在SprinbMVC配置类中

对资源放行

对访问路径放行

给涉及到的controller和实体类加注解

访问 http\://IP:端口/doc.html

5.1 具体实现案例

5.1.1. 引入maven

在pom.xml文件中加入maven引用：

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>3.0.2</version>
</dependency>

注意事项：

目前已经发行的Knife4j版本，Knife4j本身已经引入了springfox，开发者在使用时不用再单独引入Springfox的具体版本，否额会导致版本冲突。另外在网关层聚合(例如gateway)时，必须禁用Knife4j的增强模式
使用Knife4j2.0.6及以上的版本，Spring Boot的版本必须大于等于2.2.x

5.1.2. 其他文件

启动类.java

在启动类上添加swagger2\&knife4j注解

/**
 * springboot启动类
 * @Author Mosfield
 */
@SpringBootApplication
@EnableSwagger2
@EnableKnife4j
public class 启动类 {
    public static void main(String[] args) {
        SpringApplication.run(启动类.class,args);
    }
}

SwaggerConfig.java

swagger配置类

/**
 * swagger配置类
 * @Author Mosfield
 */
@Configuration
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        // 文档类型
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                // TODO: 此处配置真正的controller包路径
                .apis(RequestHandlerSelectors.basePackage("com.XXX.XXX.XXX.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                // TODO: 正式标题
                .title("标题")
                // TODO: 正式版本
                .version("1.0")
                // TODO: 正式描述
                .description("描述")
                .build();
    }
}

WebMVCConfig.java

在springMVC控制类中，进行如下两项配置：

放行swagger相关路径
将swagger涉及的目录进行资源放行

/**
 * 对springMVC框架进行控制
 * @Author Mosfield
 * @Date 2023-6-6
 */
@Configuration // 标记当前的类是一个配置类，它单独加载
public class WebMVCConfig2 implements WebMvcConfigurer {

    @Autowired
    拦截器 拦截器对象;

    /**
     * 对拦截器进行配置
     * @param registry
     */
    public void addInterceptors(InterceptorRegistry registry) {
        // 需要放行的列表
        ArrayList<String> acl = new ArrayList();
        // 【1. 放行下列swagger相关路径】
        acl.add("/webjars/**");
        acl.add("/doc.html");
        acl.add("/swagger-resources");
        acl.add("/v2/api-docs");

        //配置拦截器
        registry.addInterceptor(拦截器对象)
                //拦截
                .addPathPatterns("/**")
                //放行
                .excludePathPatterns(acl);
    }

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        // 【2.将swagger涉及的目录进行资源放行】
        registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }

}

正常启动服务器发现报错

出错原因

SpringBoot版本号太高导致的问题

如何解决

在配置文件中添加配置

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

5.1.3. 给controller和实体类加注解

web层(Controller)

注解	作用
@Api	加在类上,用于显示目标controller的所有接口输入哪个类别
@ApiOperation	加在方法上,用于描述具体方法的功能和基本描述
@ApiParam	加在形式参数上,用于描述当前参数的基本信息(name/value/required/example)

@Api(tags = "品牌相关接口")
@RequestMapping("/xx")
@RestController
public class XxxController {

    @ApiOperation(value = "品牌分页条件查询接口")
    @GetMapping("/page")
    public Result<Page> page(
        @ApiParam("当前页")Integer currentPage,
        @ApiParam("每页显示数") Integer pageSize) {
        //省略大量代码
        return xxx;
    }

}

实体类

注解	作用
@ApiModel	加在类上,描述实体类的用处和含义
@ApiModelProperty	加在成员变量上,用于成员变量的含义

@Data
@ApiModel("用户信息")
public class User {
    @ApiModelProperty(value = "用户id")
    private Integer uid;
    @ApiModelProperty(value = "用户名",required = true)
    private String username;
    @ApiModelProperty(value = "用户密码",required = true)
    private String password;
    @ApiModelProperty("用户状态")
    private Integer status;
}

5.1.4. 访问knife4j页面

访问 http\://IP:端口/doc.html

5.1.5. 附表：Knife4j 配置

各个配置属性说明如下：

属性	默认值	说明值
knife4j.enable	false	是否开启Knife4j增强模式
knife4j.cors	false	是否开启一个默认的跨域配置,该功能配合自定义Host使用
knife4j.production	false	是否开启生产环境保护策略,详情参考文档
knife4j.basic		对Knife4j提供的资源提供BasicHttp校验,保护文档
knife4j.basic.enable	false	关闭BasicHttp功能
knife4j.basic.username		basic用户名
knife4j.basic.password		basic密码
knife4j.documents		自定义文档集合，该属性是数组
knife4j.documents.group		所属分组
knife4j.documents.name		类似于接口中的tag,对于自定义文档的分组
knife4j.documents.locations		markdown文件路径,可以是一个文件夹(`classpath:markdowns/*`)，也可以是单个文件(`classpath:md/sign.md`)
knife4j.setting		前端Ui的个性化配置属性
knife4j.setting.enableAfterScript	true	调试Tab是否显示AfterScript功能,默认开启
knife4j.setting.language	zh-CN	Ui默认显示语言,目前主要有两种:中文(zh-CN)、英文(en-US)
knife4j.setting.enableSwaggerModels	true	是否显示界面中SwaggerModel功能
knife4j.setting.swaggerModelName	`Swagger Models`	重命名SwaggerModel名称,默认
knife4j.setting.enableDocumentManage	true	是否显示界面中"文档管理"功能
knife4j.setting.enableReloadCacheParameter	false	是否在每个Debug调试栏后显示刷新变量按钮,默认不显示
knife4j.setting.enableVersion	false	是否开启界面中对某接口的版本控制,如果开启，后端变化后Ui界面会存在小蓝点
knife4j.setting.enableRequestCache	true	是否开启请求参数缓存
knife4j.setting.enableFilterMultipartApis	false	针对RequestMapping的接口请求类型,在不指定参数类型的情况下,如果不过滤,默认会显示7个类型的接口地址参数,如果开启此配置,默认展示一个Post类型的接口地址
knife4j.setting.enableFilterMultipartApiMethodType	POST	具体接口的过滤类型
knife4j.setting.enableHost	false	是否启用Host
knife4j.setting.enableHomeCustom	false	是否开启自定义主页内容
knife4j.setting.homeCustomLocation		主页内容Markdown文件路径
knife4j.setting.enableSearch	false	是否禁用Ui界面中的搜索框
knife4j.setting.enableFooter	true	是否显示Footer
knife4j.setting.enableFooterCustom	false	是否开启自定义Footer
knife4j.setting.footerCustomContent	false	自定义Footer内容
knife4j.setting.enableDynamicParameter	false	是否开启动态参数调试功能
knife4j.setting.enableDebug	true	启用调试
knife4j.setting.enableOpenApi	true	显示OpenAPI规范
knife4j.setting.enableGroup	true	显示服务分组