• Swagger使用详解

    一、简介

    前言

    Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步

    Why Swagger？

    当下很多公司都采取前后端分离的开发模式，前端和后端的工作由不同的工程师完成，在这种开发模式下，维持一份及时更新且完整的 Rest API 文档将会极大的提高我们的工作效率。传统意义上的文档都是后端开发人员手动编写的，这种方式很难保证文档的及时性，这种文档久而久之也就会失去其参考意义，反而还会加大我们的沟通成本。而 swagger 给我们提供了一个全新的维护 API 文档的方式

    作为后端开放人员，最烦的事就是自己写接口文档和别人没有写接口文档，不管是前端还是后端开发，多多少少都会被接口文档所折磨，前端会抱怨后端没有及时更新接口文档，而后端又会觉得编写接口文档太过麻烦。Swagger 可以较好的接口接口文档的交互问题，以一套标准的规范定义接口以及相关的信息，就能做到生成各种格式的接口文档，生成多种语言和客户端和服务端的代码，以及在线接口调试页面等等。只需要更新 Swagger 描述文件，就能自动生成接口文档，做到前端、后端联调接口文档的及时性和便利性

    作用
    1.支持 API 自动生成同步的在线文档：使用 Swagger 后可以直接通过代码生成文档，不再需要自己手动编写接口文档了，对程序员来说非常方便

    2.提供 Web 页面在线测试 API：Swagger 生成的文档支持在线测试。参数和格式都定好了，直接在界面上输入参数对应的值即可在线测试接口

    二、SwaggerTest项目搭建

    1. pom.xml

    1. "1.0" encoding="UTF-8"?>
    2. <project xmlns="http://maven.apache.org/POM/4.0.0"
    3.          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    4.          xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    5.     <modelVersion>4.0.0modelVersion>
    6.  
    7.     <groupId>com.swaggergroupId>
    8.     <artifactId>SwaggerTestartifactId>
    9.     <version>1.0-SNAPSHOTversion>
    10.  
    11.     <properties>
    12.         <maven.compiler.source>8maven.compiler.source>
    13.         <maven.compiler.target>8maven.compiler.target>
    14.     properties>
    15.  
    16.     <dependencies>
    17.         
    18.         <dependency>
    19.             <groupId>org.springframework.bootgroupId>
    20.             <artifactId>spring-boot-starterartifactId>
    21.             <version>2.2.6.RELEASEversion>
    22.         dependency>
    23.         
    24.         <dependency>
    25.             <groupId>org.springframework.bootgroupId>
    26.             <artifactId>spring-boot-starter-webartifactId>
    27.             <version>2.2.6.RELEASEversion>
    28.         dependency>
    29.         
    30.         <dependency>
    31.             <groupId>org.projectlombokgroupId>
    32.             <artifactId>lombokartifactId>
    33.             <version>1.18.24version>
    34.         dependency>
    35.  
    36.         
    37.         <dependency>
    38.             <groupId>io.springfoxgroupId>
    39.             <artifactId>springfox-spring-webartifactId>
    40.             <version>2.9.2version>
    41.         dependency>
    42.         <dependency>
    43.             <groupId>io.springfoxgroupId>
    44.             <artifactId>springfox-swagger2artifactId>
    45.             <version>2.9.2version>
    46.         dependency>
    47.         <dependency>
    48.             <groupId>io.springfoxgroupId>
    49.             <artifactId>springfox-swagger-uiartifactId>
    50.             <version>2.9.2version>
    51.         dependency>
    52.     dependencies>
    53.  
    54. project>

    2. entity类

    1. package com.swagger.entity;
    2.  
    3. import lombok.AllArgsConstructor;
    4. import lombok.Data;
    5. import lombok.NoArgsConstructor;
    6.  
    7. @Data
    8. @AllArgsConstructor
    9. @NoArgsConstructor
    10. public class User {
    11.      private Long id;
    12.      private String name;
    13.      private int age;
    14. }

    3. controller层

    1. package com.swagger.controller;
    2.  
    3. import com.swagger.entity.User;
    4. import org.springframework.stereotype.Controller;
    5. import org.springframework.web.bind.annotation.*;
    6.  
    7. @RestController
    8. @RequestMapping("/user")
    9. public class UserController {
    10.  
    11.      @GetMapping("/getByName")
    12.      public String getByName(){
    13.           return "访问getByName成功";
    14.      }
    15.      
    16.      @PostMapping("/login")
    17.      public String login(@RequestBody User user){
    18.           return "登录成功";
    19.      }
    20. }

    三、基本使用

    1. 导入相关依赖

    1.         
    2.         <dependency>
    3.             <groupId>io.springfoxgroupId>
    4.             <artifactId>springfox-spring-webartifactId>
    5.             <version>2.9.2version>
    6.         dependency>
    7.         <dependency>
    8.             <groupId>io.springfoxgroupId>
    9.             <artifactId>springfox-swagger2artifactId>
    10.             <version>2.9.2version>
    11.         dependency>
    12.         <dependency>
    13.             <groupId>io.springfoxgroupId>
    14.             <artifactId>springfox-swagger-uiartifactId>
    15.             <version>2.9.2version>
    16.         dependency>
    17.

    2. 编写配置文件

    1. @Configuration // 配置类
    2. @EnableSwagger2 // 开启 swagger2 的自动配置
    3. public class SwaggerConfig {
    4. }

    这个时候 Swagger 已经算是整合到项目之中了，可以启动下服务，输入：http://localhost:8080/swagger-ui.html# 即可查看Swagger文档，可以看到如下信息

    • 组
    • 基本信息
    • 接口信息
    • 实体类信息

    2.1 配置基本信息

    Swagger 在自己的实例Docket中可以设置自定义基本信息于ApiInfo对象中，下图为Swagger默认的基本信息

    ApiInfo中默认的基本信息

    • title:Api Documentation
    • description:Api Documentation
    • version:1.0
    • termsOfServiceUrl:urn:tos
    • contact:无
    • license：Apache 2.0
    • licenseUrl:http://www.apache.org/licenses/LICENSE-2.0

    这些信息都不是我们需求的，我们可以在Swagger配置文件中去配置属于我们自己项目的接口文档信息，代码如下

    1. package com.swagger.config;
    2.  
    3. import org.springframework.context.annotation.Bean;
    4. import org.springframework.context.annotation.Configuration;
    5. import springfox.documentation.builders.ApiInfoBuilder;
    6. import springfox.documentation.service.ApiInfo;
    7. import springfox.documentation.service.Contact;
    8. import springfox.documentation.spi.DocumentationType;
    9. import springfox.documentation.spring.web.plugins.Docket;
    10. import springfox.documentation.swagger2.annotations.EnableSwagger2;
    11.  
    12. @Configuration // 配置类
    13. @EnableSwagger2 // 开启 swagger2 的自动配置
    14. public class SwaggerConfig {
    15.      @Bean
    16.      public Docket docket() {
    17.           // 创建一个 swagger 的 bean 实例
    18.           return new Docket(DocumentationType.SWAGGER_2)
    19.                   // 配置基本信息
    20.                   .apiInfo(apiInfo());
    21.      }
    22.  
    23.      // 基本信息设置
    24.      private ApiInfo apiInfo() {
    25.           Contact contact = new Contact(
    26.                   "Keke", // 作者姓名
    27.                   "https://blog.csdn.net/m0_63732435?spm=1011.2124.3001.5343", // 作者网址
    28.                   "1781125992@qq.com"); // 作者邮箱
    29.           return new ApiInfoBuilder()
    30.                   .title("SwaggerTest-接口文档") // 标题
    31.                   .description("这是关于Swagger学习测试的接口文档") // 描述
    32.                   .termsOfServiceUrl("https://www.baidu.com") // 跳转连接
    33.                   .version("1.0") // 版本
    34.                   .license("Swagger-的使用(详细教程)")
    35.                   .licenseUrl("https://blog.csdn.net/m0_63732435/article/details/133689227?spm=1001.2014.3001.5501")
    36.                   .contact(contact)
    37.                   .build();
    38.      }
    39.  
    40. }

    重新启动服务，效果如下

    2.2 配置接口信息

    默认情况下，Swagger是会展示所有的接口信息的，包括最基础的basic-error相关接口

    有时候我们希望不要展示 basic-error-controller 相关的接口，或者有其他需求，可以看以下代码和注释理解运用

    1. @Bean
    2.      public Docket docket() {
    3.           // 创建一个 swagger 的 bean 实例
    4.           return new Docket(DocumentationType.SWAGGER_2)
    5.                   //配置基本信息
    6.                   .apiInfo(apiInfo())
    7.                   // 配置接口信息
    8.                   .select() // 设置扫描接口
    9.                   // 配置如何扫描接口
    10.                   .apis(RequestHandlerSelectors
    11.                                   //.any() // 扫描全部的接口，默认
    12.                                   //.none() // 全部不扫描
    13.                                   .basePackage("com.swagger.controller") // 扫描指定包下的接口，最为常用
    14.                           //.withClassAnnotation(RestController.class) // 扫描带有指定注解的类下所有接口
    15.                           //.withMethodAnnotation(PostMapping.class) // 扫描带有只当注解的方法接口
    16.  
    17.                   )
    18.                   .paths(PathSelectors
    19.                                   .any() // 满足条件的路径，该断言总为true
    20.                           //.none() // 不满足条件的路径，该断言总为false（可用于生成环境屏蔽 swagger）
    21.                           //.ant("/user/**") // 满足字符串表达式路径
    22.                           //.regex("") // 符合正则的路径
    23.                   )
    24.                   .build();
    25.      }

    可以看到，basic-error相关接口我们已经去除了

    2.3 配置分组信息

    Swagger默认只有一个分组，名为default，如果不设置，所有的接口都会在这个分组下。在多模块项目下，我们通常会需要建立多个分组来分类管理这些接口，来防止接口混杂在一起

    2.3.1 分组名修改
    1.  @Bean
    2.      public Docket docket() {
    3.           // 创建一个 swagger 的 bean 实例
    4.           return new Docket(DocumentationType.SWAGGER_2)
    5.                   //设置分组名
    6.                   .groupName("admin")
    7.      }

    可以看到分组名修改为admin

    2.3.2 设置多个分组

    实际上创建几个Docket对象，就有几个分组，代码如下

    1. package com.swagger.config;
    2.  
    3. import org.springframework.context.annotation.Bean;
    4. import org.springframework.context.annotation.Configuration;
    5. import springfox.documentation.builders.ApiInfoBuilder;
    6. import springfox.documentation.builders.PathSelectors;
    7. import springfox.documentation.builders.RequestHandlerSelectors;
    8. import springfox.documentation.service.ApiInfo;
    9. import springfox.documentation.service.Contact;
    10. import springfox.documentation.spi.DocumentationType;
    11. import springfox.documentation.spring.web.plugins.Docket;
    12. import springfox.documentation.swagger2.annotations.EnableSwagger2;
    13.  
    14. @Configuration // 配置类
    15. @EnableSwagger2 // 开启 swagger2 的自动配置
    16. public class SwaggerConfig {
    17.      @Bean
    18.      public Docket docket() {
    19.           // 创建一个 swagger 的 bean 实例
    20.           return new Docket(DocumentationType.SWAGGER_2)
    21.                   //设置分组名
    22.                   .groupName("admin")
    23.                   //配置基本信息
    24.                   .apiInfo(apiInfo())
    25.                   // 配置接口信息
    26.                   .select() // 设置扫描接口
    27.                   // 配置如何扫描接口
    28.                   .apis(RequestHandlerSelectors
    29.                                   //.any() // 扫描全部的接口，默认
    30.                                   //.none() // 全部不扫描
    31.                                   .basePackage("com.swagger.controller") // 扫描指定包下的接口，最为常用
    32.                           //.withClassAnnotation(RestController.class) // 扫描带有指定注解的类下所有接口
    33.                           //.withMethodAnnotation(PostMapping.class) // 扫描带有只当注解的方法接口
    34.  
    35.                   )
    36.                   .paths(PathSelectors
    37.                                   .any() // 满足条件的路径，该断言总为true
    38.                           //.none() // 不满足条件的路径，该断言总为false（可用于生成环境屏蔽 swagger）
    39.                           //.ant("/user/**") // 满足字符串表达式路径
    40.                           //.regex("") // 符合正则的路径
    41.                   )
    42.                   .build();
    43.      }
    44.  
    45.      @Bean
    46.      public Docket docket1() {
    47.           // 创建一个 swagger 的 bean 实例
    48.           return new Docket(DocumentationType.SWAGGER_2)
    49.                   //设置分组名
    50.                   .groupName("blog")
    51.                   //配置基本信息
    52.                   .apiInfo(apiInfo())
    53.                   // 配置接口信息
    54.                   .select() // 设置扫描接口
    55.                   // 配置如何扫描接口
    56.                   .apis(RequestHandlerSelectors
    57.                                   //.any() // 扫描全部的接口，默认
    58.                                   //.none() // 全部不扫描
    59.                                   .basePackage("com.swagger.controller") // 扫描指定包下的接口，最为常用
    60.                           //.withClassAnnotation(RestController.class) // 扫描带有指定注解的类下所有接口
    61.                           //.withMethodAnnotation(PostMapping.class) // 扫描带有只当注解的方法接口
    62.  
    63.                   )
    64.                   .paths(PathSelectors
    65.                                   .any() // 满足条件的路径，该断言总为true
    66.                           //.none() // 不满足条件的路径，该断言总为false（可用于生成环境屏蔽 swagger）
    67.                           //.ant("/user/**") // 满足字符串表达式路径
    68.                           //.regex("") // 符合正则的路径
    69.                   )
    70.                   .build();
    71.      }
    72.  
    73.      // 基本信息设置
    74.      private ApiInfo apiInfo() {
    75.           Contact contact = new Contact(
    76.                   "Keke", // 作者姓名
    77.                   "https://blog.csdn.net/m0_63732435?spm=1011.2124.3001.5343", // 作者网址
    78.                   "1781125992@qq.com"); // 作者邮箱
    79.           return new ApiInfoBuilder()
    80.                   .title("SwaggerTest-接口文档") // 标题
    81.                   .description("这是关于Swagger学习测试的接口文档") // 描述
    82.                   .termsOfServiceUrl("https://www.baidu.com") // 跳转连接
    83.                   .version("1.0") // 版本
    84.                   .license("Swagger-的使用(详细教程)")
    85.                   .licenseUrl("https://blog.csdn.net/m0_63732435/article/details/133689227?spm=1001.2014.3001.5501")
    86.                   .contact(contact)
    87.                   .build();
    88.      }
    89.  
    90. }

    可以看到blog模块分组的接口文档也在UI界面中展示出来

    四、常用注解使用

    1. @ApiModel

    该注解是作用在类上的，用来描述类的一些基本信息的

    相关属性：

    • value：提供类的一个备用名，如果不设置，默认情况下将使用 class 类的名称
    • description：对于类，提供一个详细的描述信息
    • parent：这个属性用于描述的是类的一些父类信息
    • discriminator：这个属性解释起来比较麻烦，因为这个类主要体现在断言当中
    • subTypes：可以通过这个属性，指定我们想要使用的子类

    2.@ApiModelProperty

    添加和操作属性模块的数据

    1. package com.swagger.entity;
    2.  
    3. import io.swagger.annotations.ApiModel;
    4. import io.swagger.annotations.ApiModelProperty;
    5. import lombok.AllArgsConstructor;
    6. import lombok.Data;
    7. import lombok.NoArgsConstructor;
    8.  
    9. @Data
    10. @AllArgsConstructor
    11. @NoArgsConstructor
    12. @ApiModel(value = "user实体类")
    13. public class User {
    14.      @ApiModelProperty(value = "id主键")
    15.      private Long id;
    16.      @ApiModelProperty(value = "用户姓名")
    17.      private String name;
    18.      @ApiModelProperty(value = "用户年龄")
    19.      private int age;
    20. }

    可以看到Model展示出来一些描述信息

    3.@ApiOperation

    该注解用来对某个方法/接口进行描述

    1.  @GetMapping("/getByName")
    2.      @ApiOperation(value = "根据姓名查询用户")
    3.      public String getByName(){
    4.           return "访问getByName成功";
    5.      }

    可以看到接口文档这里多了 根据姓名查询用户 的描述

    4. @ApiParam

    该注解使用在方法上或者参数上，字段说明，表示对参数的添加元数据（说明或者是否必填等）

    相关属性：

    • name：参数名
    • value：参数说明
    • required：是否必填
    1.  @GetMapping("/getByName/{id}")
    2.      @ApiOperation(value = "根据id查询用户")
    3.      public String getById(@ApiParam(value = "用户id",required = true) @PathVariable Long id){
    4.           return "访问getById成功";
    5.      }

    可以看到，添加@ApiParam注解后，接口文档多了对参数的相应描述说明

    五、Swagger接口调用

    swagger 除了让前后端交互变得方便，在swagger中也可以发起请求测试接口，只需要填写好请求所需要的参数信息即可

    点击Excute就可以看到接口响应的结果了

    六、添加请求头

    在登录注册类似涉及安全验证的业务，例如SpringSecurity框架中我们的接口是需要获取请求头信息的，这样的话就还需要在 swagger 配置中添加请求头的配置。

    1.     @Bean
    2.     public Docket docket() {
    3.         // 设置请求头
    4.         List parameters = new ArrayList<>();
    5.         parameters.add(new ParameterBuilder()
    6.                 .name("token") // 字段名
    7.                 .description("token") // 描述
    8.                 .modelRef(new ModelRef("string")) // 数据类型
    9.                 .parameterType("header") // 参数类型
    10.                 .defaultValue("default value") // 默认值：可自己设置
    11.                 .hidden(true) // 是否隐藏
    12.                 .required(false) // 是否必须
    13.                 .build());
    14.  
    15.         // 创建一个 swagger 的 bean 实例
    16.         return new Docket(DocumentationType.SWAGGER_2)
    17.                 .groupName("mike") // 修改组名为 "mike"
    18.                 // 配置接口信息
    19.                 .select() // 设置扫描接口
    20.                 // 配置如何扫描接口
    21.                 .apis(RequestHandlerSelectors
    22.                         .basePackage("com.duojiala.mikeboot.controller") // 扫描指定包下的接口，最为常用
    23.                 )
    24.                 .paths(PathSelectors
    25.                         .any() // 满足条件的路径，该断言总为true
    26.                 )
    27.                 .build()
    28.  
    29.                 // 添加请求头参数
    30.                 .globalOperationParameters(parameters);
    31.     }

    接口

    1.     @GetMapping(value = "/getToken")
    2.     @ApiOperation(value = "获取请求头中的token信息")
    3.     public void getToken(
    4.             @RequestHeader(value = "token",required = true) String token
    5.     ) {
    6.         // 直接获取 token 信息
    7.         System.out.println("token = " + token);
    8.  
    9.         // 通过代码获取
    10.         ServletRequestAttributes servletRequestAttributes = (ServletRequestAttributes) RequestContextHolder.getRequestAttributes();
    11.         if (servletRequestAttributes != null) {
    12.             HttpServletRequest request = servletRequestAttributes.getRequest();
    13.             String header = request.getHeader("token");
    14.             System.err.println("header = " + header);
    15.         }
    16.     }

    这样重启服务，接口就可以设置请求头了

    执行后，后端控制台可以打印http请求带来的token的信息

  • 相关阅读:
    【通信】两层无线 Femtocell 网络上行链路中的最优功率分配附matlab代码
    【python】（一）字符串基本操作
    Qt开发_调用OpenCV(3.4.7)设计完成人脸检测系统
    vue 使用mapbox对当前行政区划进行反选遮罩
    基于粒子群优化的BP神经网络（分类应用） - 附代码
    DC-2靶场渗透测试实验整理
    130道基础OJ编程题之: 39 ~ 46 道
    Android Retrofit
    8-6选择排序-简单选择排序
    LeetCode刷题3：哈希篇
  • 原文地址：https://blog.csdn.net/m0_63732435/article/details/133689227