Swagger与Knife4j学习笔记

Swagger

介绍

在前后端分离开发的过程中，前端和后端需要进行 API 对接进行交互，就需要一个 API 规范文档，方便前后端的交互，但 API 文档不能根据代码的变化发生实时动态的改变，这样后端修改了接口，前端不能及时获取最新的接口，导致调用出错，需要手动维护 API 文档，加大了开发的工作量和困难，而 Swagger 的出现就是为了解决这一系列的问题。

Swagger 是一个非常流行的 API 框架，用于自动生成可视化的 Restful 风格的 API 文档，支持在线调用各个后端 API 接口。

作用

• 代码改变，文档自动跟随改变
• 前后端分离架构下，前端工程师可以通过 Swagger 实时跟踪后端程序的最新 API ，提高了开发效率
• 接口文档在线自动生成
• 功能测试

基本使用

1. 在 Web 工程中引入 Swagger 的相关依赖

   <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
   <dependency>
       <groupId>io.springfox</groupId>
       <artifactId>springfox-swagger-ui</artifactId>
       <version>2.9.2</version>
   </dependency>
   
   <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
   <dependency>
       <groupId>io.springfox</groupId>
       <artifactId>springfox-swagger2</artifactId>
       <version>2.9.2</version>
   </dependency>
   

2. 在启动类（或配置类）中添加注解@EnableSwagger2

   @EnableSwagger2 注解会开启 Swagger 的相关功能，并自动扫描当前类所在的包以及子包

3. 启动项目，访问 http://localhost:8080/swagger-ui.html

基本配置

@Configuration // 代表这是一个配置类
@EnableSwagger2 // 开启 Swagger2
public class SwaggerConfig {

    // 创建 Swagger Bean 交给 Spring 容器进行管理
    @Bean
    public Docket docket() {
        // Docket: Swagger 全局配置对象
        // DocumentationType: 指定文档类型为 SWAGGER_2
        return new Docket(DocumentationType.SWAGGER_2)
                // swagger信息
                .apiInfo(apiInfo());
        		// 配置是否开启 Swagger，若为false，则浏览器不能访问
                .enable(false);
    }

    // Swagger文档信息
    public ApiInfo apiInfo() {
        // 作者信息
        Contact contact = new Contact(
                // 文档发布者的名称
                "OneOne",
                // 文档发布者的网站地址
                "https://gitee.com/one1_yaya",
                // 文档发布者的电子邮箱
                "599777737@qq.com"
        );
        return new ApiInfo(
                // 标题
                "项目标题 - API",
                // 文档描述
                "具体的文档描述",
                // 版本号
                "1.0",
                // 服务组url地址
                "urn:tos", 
                // 作者信息
                contact,
                // 开源组织
                "Apache 2.0",
                // 开源地址
                "http://www.apache.org/licenses/LICENSE-2.0",
                // 集合
                new ArrayList()
        );
    }
}

常用注解

注解	说明
@Api(tags = “xxx模块说明”)	用在请求的类上，例如Controller，表示对类的说明
@ApiModel(“对实体类的说明”)	用在类上，通常是实体类，表示一个返回响应数据的信息
@ApiOperation(“接口方法的说明”)	用在请求的方法上，说明方法的用途、作用
@ApiParam(“对参数的说明”)	作用在参数上，required为true表示必传参数
@ApiModelProperty(value=“属性说明”,hidden=true,required=true)	用在属性上，描述响应类的属性，hidden为true表示不显示此信息，required为true表示该属性添加或修改数据时为必填参数

Knife4j

简介

Knife4j 是为 Java MVC 框架集成 Swagger 生成 API 文档的增强解决方案，它的前身是 swagger-bootstrap-ui，后来改名为 Knife4j 是希望它像一把匕首一样小巧、轻量并功能强悍。

基本使用

1. 引入依赖

    <!-- https://doc.xiaominfo.com/knife4j/documentation/get_start.html-->
   <dependency>
       <groupId>com.github.xiaoymin</groupId>
       <artifactId>knife4j-spring-boot-starter</artifactId>
       <version>3.0.3</version>
   </dependency>
   

2. 配置类 - 与 Swagger 类似

   package com.one.project.config;
   
   import org.springframework.context.annotation.Bean;
   import org.springframework.context.annotation.Configuration;
   import springfox.documentation.builders.ApiInfoBuilder;
   import springfox.documentation.builders.PathSelectors;
   import springfox.documentation.builders.RequestHandlerSelectors;
   import springfox.documentation.service.Contact;
   import springfox.documentation.spi.DocumentationType;
   import springfox.documentation.spring.web.plugins.Docket;
   import springfox.documentation.swagger2.annotations.EnableSwagger2;
   
   /**
    * Knife4j 接口文档配置
    *
    * https://doc.xiaominfo.com/knife4j/documentation/get_start.html
    *
    * @author OneOne
    */
   @Configuration
   @EnableSwagger2
   public class Knife4jConfiguration {
   
       @Bean(value = "defaultApi2")
       public Docket defaultApi2() {
           return new Docket(DocumentationType.SWAGGER_2)
                   .apiInfo(new ApiInfoBuilder()
                           .title("oneapi-backend")
                           .description("oneapi-backend")
                           .termsOfServiceUrl("https://gitee.com/one1_yaya")
                           .contact(new Contact("OneOne", "https://gitee.com/one1_yaya", "599777737@qq.com"))
                           .version("1.0")
                           .build())
                   .select()
                   // 这里指定Controller扫描包路径
                   .apis(RequestHandlerSelectors.basePackage("com.one.project.controller"))
                   .paths(PathSelectors.any())
                   .build();
       }
   }