Swagger使用详解

Bugman.2023-10-08 22:30

一、简介

前言

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

Why Swagger？

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

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

作用

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

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

二、SwaggerTest项目搭建

1. pom.xml

复制代码 
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.swagger</groupId>
    <artifactId>SwaggerTest</artifactId>
    <version>1.0-SNAPSHOT</version>

    <properties>
        <maven.compiler.source>8</maven.compiler.source>
        <maven.compiler.target>8</maven.compiler.target>
    </properties>

    <dependencies>
        <!--        springboot 启动依赖-->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter</artifactId>
            <version>2.2.6.RELEASE</version>
        </dependency>
        <!--     springboot web 依赖-->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
            <version>2.2.6.RELEASE</version>
        </dependency>
        <!--lombok依赖-->
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <version>1.18.24</version>
        </dependency>

        <!-- swagger -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-spring-web</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>
    </dependencies>

</project>

2. entity类

复制代码 
package com.swagger.entity;

import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

@Data
@AllArgsConstructor
@NoArgsConstructor
public class User {
     private Long id;
     private String name;
     private int age;
}

3. controller层

复制代码 
package com.swagger.controller;

import com.swagger.entity.User;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/user")
public class UserController {

     @GetMapping("/getByName")
     public String getByName(){
          return "访问getByName成功";
     }
     
     @PostMapping("/login")
     public String login(@RequestBody User user){
          return "登录成功";
     }
}

三、基本使用

1. 导入相关依赖

复制代码 
        <!-- swagger -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-spring-web</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

2. 编写配置文件

复制代码 
@Configuration // 配置类
@EnableSwagger2 // 开启 swagger2 的自动配置
public class SwaggerConfig {
}

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

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

2.1 配置基本信息

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

ApiInfo中默认的基本信息

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

复制代码 
package com.swagger.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration // 配置类
@EnableSwagger2 // 开启 swagger2 的自动配置
public class SwaggerConfig {
     @Bean
     public Docket docket() {
          // 创建一个 swagger 的 bean 实例
          return new Docket(DocumentationType.SWAGGER_2)
                  // 配置基本信息
                  .apiInfo(apiInfo());
     }

     // 基本信息设置
     private ApiInfo apiInfo() {
          Contact contact = new Contact(
                  "Keke", // 作者姓名
                  "https://blog.csdn.net/m0_63732435?spm=1011.2124.3001.5343", // 作者网址
                  "[email protected]"); // 作者邮箱
          return new ApiInfoBuilder()
                  .title("SwaggerTest-接口文档") // 标题
                  .description("这是关于Swagger学习测试的接口文档") // 描述
                  .termsOfServiceUrl("https://www.baidu.com") // 跳转连接
                  .version("1.0") // 版本
                  .license("Swagger-的使用(详细教程)")
                  .licenseUrl("https://blog.csdn.net/m0_63732435/article/details/133689227?spm=1001.2014.3001.5501")
                  .contact(contact)
                  .build();
     }

}

重新启动服务，效果如下

2.2 配置接口信息

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

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

复制代码 
@Bean
     public Docket docket() {
          // 创建一个 swagger 的 bean 实例
          return new Docket(DocumentationType.SWAGGER_2)
                  //配置基本信息
                  .apiInfo(apiInfo())
                  // 配置接口信息
                  .select() // 设置扫描接口
                  // 配置如何扫描接口
                  .apis(RequestHandlerSelectors
                                  //.any() // 扫描全部的接口，默认
                                  //.none() // 全部不扫描
                                  .basePackage("com.swagger.controller") // 扫描指定包下的接口，最为常用
                          //.withClassAnnotation(RestController.class) // 扫描带有指定注解的类下所有接口
                          //.withMethodAnnotation(PostMapping.class) // 扫描带有只当注解的方法接口

                  )
                  .paths(PathSelectors
                                  .any() // 满足条件的路径，该断言总为true
                          //.none() // 不满足条件的路径，该断言总为false（可用于生成环境屏蔽 swagger）
                          //.ant("/user/**") // 满足字符串表达式路径
                          //.regex("") // 符合正则的路径
                  )
                  .build();
     }

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

2.3 配置分组信息

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

2.3.1 分组名修改
复制代码 
 @Bean
     public Docket docket() {
          // 创建一个 swagger 的 bean 实例
          return new Docket(DocumentationType.SWAGGER_2)
                  //设置分组名
                  .groupName("admin")
     }

可以看到分组名修改为admin

2.3.2 设置多个分组

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

复制代码 
package com.swagger.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.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration // 配置类
@EnableSwagger2 // 开启 swagger2 的自动配置
public class SwaggerConfig {
     @Bean
     public Docket docket() {
          // 创建一个 swagger 的 bean 实例
          return new Docket(DocumentationType.SWAGGER_2)
                  //设置分组名
                  .groupName("admin")
                  //配置基本信息
                  .apiInfo(apiInfo())
                  // 配置接口信息
                  .select() // 设置扫描接口
                  // 配置如何扫描接口
                  .apis(RequestHandlerSelectors
                                  //.any() // 扫描全部的接口，默认
                                  //.none() // 全部不扫描
                                  .basePackage("com.swagger.controller") // 扫描指定包下的接口，最为常用
                          //.withClassAnnotation(RestController.class) // 扫描带有指定注解的类下所有接口
                          //.withMethodAnnotation(PostMapping.class) // 扫描带有只当注解的方法接口

                  )
                  .paths(PathSelectors
                                  .any() // 满足条件的路径，该断言总为true
                          //.none() // 不满足条件的路径，该断言总为false（可用于生成环境屏蔽 swagger）
                          //.ant("/user/**") // 满足字符串表达式路径
                          //.regex("") // 符合正则的路径
                  )
                  .build();
     }

     @Bean
     public Docket docket1() {
          // 创建一个 swagger 的 bean 实例
          return new Docket(DocumentationType.SWAGGER_2)
                  //设置分组名
                  .groupName("blog")
                  //配置基本信息
                  .apiInfo(apiInfo())
                  // 配置接口信息
                  .select() // 设置扫描接口
                  // 配置如何扫描接口
                  .apis(RequestHandlerSelectors
                                  //.any() // 扫描全部的接口，默认
                                  //.none() // 全部不扫描
                                  .basePackage("com.swagger.controller") // 扫描指定包下的接口，最为常用
                          //.withClassAnnotation(RestController.class) // 扫描带有指定注解的类下所有接口
                          //.withMethodAnnotation(PostMapping.class) // 扫描带有只当注解的方法接口

                  )
                  .paths(PathSelectors
                                  .any() // 满足条件的路径，该断言总为true
                          //.none() // 不满足条件的路径，该断言总为false（可用于生成环境屏蔽 swagger）
                          //.ant("/user/**") // 满足字符串表达式路径
                          //.regex("") // 符合正则的路径
                  )
                  .build();
     }

     // 基本信息设置
     private ApiInfo apiInfo() {
          Contact contact = new Contact(
                  "Keke", // 作者姓名
                  "https://blog.csdn.net/m0_63732435?spm=1011.2124.3001.5343", // 作者网址
                  "[email protected]"); // 作者邮箱
          return new ApiInfoBuilder()
                  .title("SwaggerTest-接口文档") // 标题
                  .description("这是关于Swagger学习测试的接口文档") // 描述
                  .termsOfServiceUrl("https://www.baidu.com") // 跳转连接
                  .version("1.0") // 版本
                  .license("Swagger-的使用(详细教程)")
                  .licenseUrl("https://blog.csdn.net/m0_63732435/article/details/133689227?spm=1001.2014.3001.5501")
                  .contact(contact)
                  .build();
     }

}

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

四、常用注解使用

1. @ApiModel

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

相关属性：

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

2.@ApiModelProperty

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

复制代码 
package com.swagger.entity;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

@Data
@AllArgsConstructor
@NoArgsConstructor
@ApiModel(value = "user实体类")
public class User {
     @ApiModelProperty(value = "id主键")
     private Long id;
     @ApiModelProperty(value = "用户姓名")
     private String name;
     @ApiModelProperty(value = "用户年龄")
     private int age;
}

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

3.@ApiParam

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

复制代码 
 @GetMapping("/getByName")
     @ApiOperation(value = "根据姓名查询用户")
     public String getByName(){
          return "访问getByName成功";
     }

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

4. @ApiParam

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

相关属性：

  • name：参数名
  • value：参数说明
  • required：是否必填
复制代码 
 @GetMapping("/getByName/{id}")
     @ApiOperation(value = "根据id查询用户")
     public String getById(@ApiParam(value = "用户id") @PathVariable Long id){
          return "访问getById成功";
     }

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

相关推荐
qq_534452522 分钟前
【算法 day02】LeetCode 209.长度最小的子数组 | 59.螺旋矩阵II
java·算法·leetcode·职场和发展
向上的车轮7 分钟前
语言特性适用的场景：卫星、火箭控制系统用什么开发语言？
java·开发语言·c++·c#·c·ada
zhendeWD15 分钟前
springboot项目启动报错：spring boot application in default package
java·spring boot·后端
风象南24 分钟前
SpringBoot实现6种JWT令牌失效方案
java·spring boot·后端
llwszx29 分钟前
“从HTTP到TCP/IP的旅程“-----深入浅出Java Web通信
java·websocket·网络协议·tcp/ip·spring·http
苹果醋31 小时前
SpringCloud Alibaba场景实践（Nacos篇）
java·运维·spring boot·mysql·nginx
云边小网安2 小时前
java集合（十） ---- LinkedList 类
java·开发语言·青少年编程·java集合
乐神嘎嘎嘎2 小时前
springboot速通
java·spring boot
Zephyrtoria3 小时前
区间合并：区间合并问题
java·开发语言·数据结构·算法
热门推荐
01Coze扣子平台完整体验和实践（附国内和国际版对比）02DeepSeek各版本说明与优缺点分析03KGG转MP3工具|非KGM文件|解密音频04扣子（coze）实战|我用扣子搭建了一个自动分析小红薯笔记内容的AI应用|详细步骤拆解05从零安装 LLaMA-Factory 微调 Qwen 大模型成功及所有的坑06YOLOv8入门 | 重要性能衡量指标、训练结果评价及分析及影响mAP的因素【发论文关注的指标】07AI Agent | Coze 插件使用指南：从功能解析到实操步骤08零代码入门 | Coze——让大模型接入自己的数据库09【SpeedAI科研小助手】2分钟极速解决知网维普重复率、AIGC率过高，一键全文降！文件格式不变，公式都保留的！10基于单片机的智能环境监测系统