SpringBoot 整合 Swagger

官网：API Documentation & Design Tools for Teams | Swagger

1、Swagger 介绍

Swagger 是一个简单但功能强大的 API 表达工具。它具有地球上最大的 API 具生态系统，数以千计的开发人员，使用几乎所有的现代编程语言，都在支持和使用 Swagger 。使用 Swagger 生成 API ，我们可以得到交互式文档，自动生成代码的 SDK 以及 API 的发现特性等。

前后端分离的项目，接口文档的存在十分重要。与手动编写接口文档不同, swagger 是一个自动生成接口文档的工具，在需求不断变更的环境下，手动编写文档的效率实在太低。与 swagger2 相比新版的 swagger3 配置更少，使用更加方便。

2、Swagger 作用

• 将项目中所有的接口展现在页面上，这样后端程序员就不需要专门为前端使用者编写专门的接口文档
• 当接口更新之后，只需要修改代码中的 Swagger 描述就可以实时生成新的接口文档了，从而规避了接口文档老旧不能使用的问题
• 通过 Swagger 页面，我们可以直接进行接口调用，降低了项目开发阶段的调试成本

现在SWAGGER官网主要提供了几种开源工具，提供相应的功能。可以通过配置甚至是修改源码以达到你想要的效果

• Swagger odegen：通过 Codegen 可以将描述文件生成 html 格式和 cwiki 形式的接口文档，同时也能生成多钟语言的服务端和客户端的代码。支持通过jar包,docker，node等方式在本地化执行生成。也可以在后面的 Swagger Editor 中在线生成
• Swagger Ul： 提供了一个可视化的 UI 页面展示描述文件。接口的调用方、测试、项目经理等都可以在该页面中对相关接口进行查阅和做一些简单的接口请求。该项目支持在线导入描述文件和本地部署 UI 项目
• Swagger Editor： 类似于 markendown 编辑器的编辑 Swagger 描述文件的编辑器，该编辑支持实时预览描述文件的更新效果。也提供了在线编辑器和本地部署编辑器两种方式
• Swagger Inspector：感觉和 Postman 差不多，是一个可以对接口进行测试的在线版的postman。比在5wagger Ul 里面做接口请求，会返回更多的信息，也会保存你请求的实际请求参数等数据
• Swagger Hub：集成了上面所有项目的各个功能，你可以以项目和版本为单位，将你的描述文件上传到Swagger Htub 中。在 Swagger Hub 中可以完成上面项目的所有工作，需要注册账号，分免费版和收费版。

3、Swagger HelloWorld 实现

1. 在项目中添加依赖

   <dependency>
       <groupId>io.springfox</groupId>
       <artifactId>springfox-boot-starter</artifactId>
       <version>3.0.0</version>
   </dependency>
   

   这里用的是 springfox ，Swagger 可以看作是一个遵循了 OpenAPl 规范的一项技术，而 springfox 则是这项技术的具体实现。

   类似 JDBC 是一套技术规范，各大数据库都有 JDBC 的实现

2. 在主启动类中开启 Swagger

   @EnableOpenApi

   package cn.edu.hziee;
   
   import org.springframework.boot.SpringApplication;
   import org.springframework.boot.autoconfigure.SpringBootApplication;
   import springfox.documentation.oas.annotations.EnableOpenApi;
   
   @SpringBootApplication
   @EnableOpenApi
   public class MainApplication {
       public static void main(String[] args) {
           SpringApplication.run(MainApplication.class, args);
       }
   }
   

3. 新建 HelloSwaggerController

   package cn.edu.hziee.controller;
   
   import org.springframework.web.bind.annotation.RequestMapping;
   import org.springframework.web.bind.annotation.RestController;
   
   @RestController
   public class HelloSwagger {
   
       @RequestMapping("hello-swagger")
       public String helloSwagger(){
           return "helloSwagger!";
       }
   }
   

4. 测试

   输入：http://localhost:8080/swagger-ui/

   注意：URL：swagger-ui 后面有个 /

   看到如下页面：
   

   • 分组定义信息
     

   • API 文档信息

• 接口文档信息
  

  • 展开 HelloSwagger 接口定义
    

  • 点击 GET
    

    我们可以看到，接口没有参数，返回值是 String 类型

    这里描述了完整的接口定义信息;前端开发人员一目了然，假如接口定义变化，前端开发人员刷新下swagger-ui 就能及时看到，比起以往的人工编写接口文档方便很多

4、Swagger 注解

Swagger提供了一些配置用来描述接口，下面是一些常用的注解，必须掌握

Api:用在请求的类上，表示对类的说明
	tags="说明该类的作用，可以在uI界面上看到的注解"
	value="该参数没什么意义，在uI界面上也看到，所以不需要配置"

@Apioperation:用在请求的方法上，说明方法的用途、作用
	value="说明方法的用途、作用"
	notes="方法的备注说明"
	
@ApiImplicitParams :用在请求的方法上，表示一组参数说明
	@ApiImplicitparam:用在@ApiImplicitparams注解中，指定一个请求参数的各个方面
		name:参数名
		value:参数的汉字说明、解释
		required:参数是否必须传
		paramType:参数放在哪个地方
			header -->请求参数的获取:@RequestHeader
			query -->请求参数的获取:@RequestParam
			path（用于restfu1接口）-->请求参数的获取:@Pathvariable
			div(不常用)
			form（不常用)
		dataType:参数类型，默认string，其它值dataType="Integer"
		defaultvalue:参数的默认值
		
@ApiResponses:用在请求的方法上，表示一组响应
	@ApiResponse:用在@ApiResponses中，一般用于表达一个错误的响应信息
		code:数字，例如400
		message:信息,例如""请求参数没填好"
		response:抛出异常的类

@ApiModel:用于响应类上，表示一个返回响应数据的信息
		(这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitPar am			注解进行描述的时候)
	@ApiModelProperty:用在属性上,描述响应类的属性

4.1、@API、@Api0peration

我们在类上添加 @API 注解，以及在方法上添加 @Api0peration 注解。增加中文注释

package cn.edu.hziee.controller;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@Api("测试 Swagger 页面")
@RestController
public class HelloSwagger {

    @ApiOperation("测试方法")
    @RequestMapping("hello-swagger")
    public String helloSwagger(){
        return "helloSwagger!";
    }
}

4.2、@ApiImplicitParams、@ApiImplicitParam

@PostMapping("/search")
@ApiImplicitParams({
    @ApiImplicitParam(name = "name", value = "姓名", required = true, paramType = "query"),
    @ApiImplicitParam(name = "age", value = "年龄", required = true, paramType = "query", dataType = "Integer")
})
@ApiOperation("测试查询")
public String search(String name, Integer age){
    return name   ":"   age;
}

4.3、@ApiModel、@ApiModelProperty

实体类：

package cn.edu.hziee.pojo;

import com.baomidou.mybatisplus.annotation.*;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

import java.util.Date;

@Data
@NoArgsConstructor
@AllArgsConstructor
public class User {

    @ApiModelProperty("ID 主键")
    @TableId(value = "id",type = IdType.AUTO)
    private Long id;
    @ApiModelProperty("名字")
    private String name;
    @ApiModelProperty("密码")
    private String pwd;
    @ApiModelProperty("邮箱")
    private String email;
    @ApiModelProperty("年龄")
    private Short age;
    @ApiModelProperty("性别")
    private String gender;
    @TableLogic
    private Integer deleted;
    @Version
    private Integer version;
    @TableField(fill = FieldFill.INSERT)
    private Date gmtCreate;
    @TableField(fill = FieldFill.INSERT_UPDATE)
    private Date gmtModified;
}

controller：

@PostMapping("/search")
@ApiImplicitParams({
    @ApiImplicitParam(name = "name", value = "姓名", required = true, paramType = "query"),
    @ApiImplicitParam(name = "age", value = "年龄", required = true, paramType = "query", dataType = "Integer")
})
@ApiOperation("测试查询")
public String search(String name, Integer age){
    return name   ":"   age;
}

@PostMapping("/add")
@ApiOperation("测试添加")
public String add(User user){
    return user.getName()   ":"  user.getAge();
}

4.3、@ApiResponses、@ApiResponse

controller

@GetMapping("/user/{id}")
@ApiOperation("根据用户ID获取用户信息")
@ApiImplicitParams({
    @ApiImplicitParam(name = "id", value = "用户ID", required = true, paramType = "path")
})
@ApiResponses({
    @ApiResponse(code = 500,message = "内部代码错误"),
    @ApiResponse(code = 400,message = "请求参数没填好"),
    @ApiResponse(code = 404, message = "请求路径没有或者跳转路径不对")
})
public User getUserById(@PathVariable("id") Long id){
    Short age = 21;
    return new User(id, "jack", age);
}

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-B1fdlKpM-1649427563790)(D:\Typora\Typora\Typora\typora-user-images\image-20211101005739032.png)]

4、Swagger 接口测试

swagger-ui 图形客户端提供了接口测试功能

默认情况下，这些参数都是不能填写的，都是禁用的

点击"Try it out" 按钮，即可开启接口测试功能：

这篇好文章是转载于：学新通技术网