Swagger 学习笔记 | Swagger 简介 | Springfox 简介 | Springfox 2.9.2 常用注解

文章目录

一、Swagger 简介
二、Springfox 简介
三、Springfox2.9.2 常用注解
四、SpringBoot 整合 Swagger2
- 4.1 引入Maven依赖
- 4.2 项目配置
- 4.3 数据模型
- 4.4 Controller层
- 4.5 SpringBoot 启动类
- 4.6 运行并测试案例

一、Swagger 简介

OpenAPI 简介

OpenAPI 规范（以前称为 Swagger 规范）是 REST API的API 描述格式。OpenAPI 文件可以描述整个 API，包括：
1）可用端点 ( /users) 和每个端点上的操作 ( GET /users, POST /users)
2）操作参数每个操作的输入和输出
3）身份验证方法
4）联系信息、许可、使用条款和其他信息
API 规范可以用 YAML 或 JSON 编写

Swagger 简介

Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。主要的 Swagger 工具包括：
1）Swagger Editor – 基于浏览器的编辑器，可以在其中编写 OpenAPI 规范
2）Swagger UI – 将 OpenAPI 规范呈现为交互式 API 文档
3）Swagger Codegen – 从 OpenAPI 规范生成服务器存根和客户端库

Swagger 作用

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

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

二、Springfox 简介

Springfox 介绍文章

Springfox 是一个使用Java语言开发开源的API Doc的框架，它的前身是swagger-springmvc，可以将我们的Controller中的方法以文档的形式展现。官方定义为： Automated JSON API documentation for API’s built with Spring。

Springfox 目前有1、2、3三种版本，从v3版本开始则有较大变化，据官方文档介绍，变化如下：

删除早期版本的一些依赖。特别是删除springfox-swagger2和springfox-swagger-ui依赖。
删除 @EnableSwagger2 注释
添加 springfox-boot-starter 支持springboot使用的起步依赖
Springfox 3.x 删除了对 guava 和其他第三方库的依赖（但仍然依赖于 spring 插件和开放 api 库，用于注释和模型）

Springfox 的作用

1）将前后端有效分离，并保证了API与文档的实时同步
2）使用springfox生成的接口文档直观可视，支持查看各个接口需要的参数和返回结果
3）springfox支持在线测试，可实时检查参数和返回值

接下来主要以v2版本为主。

三、Springfox2.9.2 常用注解

Springfox官方配置文档

@Api

作用：标记类，控制整个类生成接口信息的内容，通常写在MVC中的控制器类上。

常用参数说明：

tags，类的名称，可以有多个值，定义几个别名，在UI视图中就会显示几个控制器访问菜单
description，描述，已过时

使用案例：

@RestController
@RequestMapping("/user")
@Api(tags = {"用户控制层"}, description = "描述被弃用了，但依然可以使用")
public class UserController{
	...
}

@ApiOperation

作用：标记方法，将方法显示到Swagger生成的文档中

常用参数说明：

value，方法的名称
notes，方法的记录
httpMethod, 请求方式

使用案例：

@ApiOperation(value = "用户注册", httpMethod = "POST")
@PostMapping("/register")
public R register(User user){
    return userService.register(user) ?
            R.success("注册成功", user)
                : R.fail("注册失败", new User());
}

@ApiParam

作用：描述参数，作用于方法中的参数，将参数的描述显示到文档中

常用参数说明：

name，参数名
value，参数描述
require， true/false，表示参数是否必要

使用案例：

@ApiOperation(value = "用户注册", httpMethod = "POST")
@PostMapping("/register")
public R register(@ApiParam(name="用户(user)", value = "注册的用户信息") User user){
    return userService.register(user) ?
            R.success("注册成功", user)
                : R.fail("注册失败", new User());
}

@ApiIgnore

作用：忽略，当前注解描述的方法或类型，不生成API帮助文档

使用案例：

@ApiIgnore
@ApiOperation(value = "用户注册", httpMethod = "POST")
@PostMapping("/register")
public R register(@ApiParam(name="用户(user)", value = "注册的用户信息") User user){
    ...
}

@ApiImplicitParam

作用：作用于@Api类中的方法，用于描述方法中的单个参数

常用参数说明：

name，参数名，需要与方法中的参数名对应
value，参数描述
require， true/false，表示参数是否必要
dataType，参数类型
使用案例：

 @ApiOperation(value = "用户注册", httpMethod = "POST")
 @ApiImplicitParam(name = "user", value = "注册的用户信息")
 @PostMapping("/register")
 public R register(@ApiParam(name="用户", value = "注册的用户信息") User user){
     ...
 }

@ApiImplicitParams

作用：作用于@Api类中的方法，用于描述方法中的多个参数

常用参数说明：{ @ApiImplicitParam(…) , @ApiImplicitParam(…) }

@ApiOperation(value = "修改用户信息", httpMethod = "POST")
@ApiImplicitParams({
        @ApiImplicitParam(
                name = "userId", value = "用户的ID",
                required = true, dataType = "long", paramType = "path"),
        @ApiImplicitParam(
                name = "user", value = "修改后的用户信息(id不可更改)",
                dataType = "User", paramType = "query")
})
@PostMapping("/update/{userId}")
public R modify(@PathVariable Long userId, User user){
    ...
}

@ApiModel

作用：描述一个实体类型，这个实体类型如果称为任何一个生成api帮助文档方法的返回值类型时，该注解被解析。

常用参数说明：

vlaue，实体类的名称（唯一）
description，实体类的描述

@ApiModelProperty

作用：描述@ApiModel实体类型中的属性

常用参数说明：

value，参数的名称（唯一）
name，参数的名称
required，true/false，表示属性是否必须
example, 值的范例
hidden, true/false，表示是否隐藏

使用案例：

package cn.uni.rbac.po;

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

import java.io.Serializable;
import java.util.List;

@Data
@ApiModel("用户表实体对象")
public class User implements Serializable {
    @ApiModelProperty("用户ID")
    private Long id;

    @ApiModelProperty("用户名")
    private String name;

    @ApiModelProperty("用户密码")
    private String password;

    @ApiModelProperty("盐")
    private String salt;

    @ApiModelProperty("外键: 角色表对象")
    private List roleList;
}

四、SpringBoot 整合 Swagger2

接下来使用SpringBoot 整合 Swagger2，实现简单的API文档生成

案例的项目结构：

运行结果：

版本选型：

IDEA 2022 专业版
Maven3.8.4
JDK 8
SpringBoot 2.6.9
Springfox 2.9.2
Springfox-ui 2.9.2

4.1 引入Maven依赖

pom.xml



    4.0.0
    
        org.springframework.boot
        spring-boot-starter-parent
        2.6.9
         
    
    cn.uni
    swagger-demo
    0.0.1-SNAPSHOT
    swagger-demo
    swagger-demo
    
        1.8
    
    
        
            org.springframework.boot
            spring-boot-starter-web
        
        
        
            org.projectlombok
            lombok
            true
        
        
            org.springframework.boot
            spring-boot-starter-test
            test
        

        
            io.springfox
            springfox-swagger-ui
            2.9.2
        
        
            io.springfox
            springfox-swagger2
            2.9.2
        

    

    
        
            
                org.springframework.boot
                spring-boot-maven-plugin
                
                    
                        
                            org.projectlombok
                            lombok

4.2 项目配置

Springfox Swagger2 配置：config/SwaggerConfig.java

package cn.uni.config;

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

@Configuration
@EnableSwagger2
// http://localhost:8080/swagger-ui/index.html
public class SwaggerConfig {
    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2) //
                .select()
                // 设置扫描的路径
                .apis(RequestHandlerSelectors.basePackage("cn.uni.controller"))
                .build();
    }
}

SpringMVC配置，为解决SpringBoot高版本的mvc路径匹配规则与Springfox-Swagger-ui 冲突，需要进行以下的配置：config/WebMvcConfig.java

package cn.uni.config;

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;

@Configuration
public class WebMvcConfig extends WebMvcConfigurationSupport {
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("
@Data
@AllArgsConstructor
@NoArgsConstructor
@ApiModel(value = "前后端交互")
public class R implements Serializable {

    @ApiModelProperty(value = "响应代码")
    private Integer code;
    @ApiModelProperty(value="响应的信息")
    private String msg;
    @ApiModelProperty(value="响应的数据")
    private T data;

    
    public static R success(String msg, T data){
        return new R(200, msg, data);
    }
    
    public static R fail(String msg, T data){
        return new R(400, msg, data);
    }
    
    public static R custom(int code, String msg, T data){
        return  new R(code, msg, data);
    }
}

4.4 Controller层

这里模拟注册与登录，调用接口后直接返回成功的信息和请求的数据。

package cn.uni.controller;

import cn.uni.pojo.po.User;
import cn.uni.pojo.po.R;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@Api(tags = "用户操作相关的控制层")
@RestController
@RequestMapping("/user")
public class UserController {
    @ApiOperation(value = "用户注册", httpMethod = "POST")
    @ApiImplicitParam(name = "user", value = "注册的用户信息")
    @PostMapping("/register")
    public R register(@ApiParam(name="用户", value = "注册的用户信息") User user){
        return R.success("注册成功", user);
    }
    @ApiOperation(value = "用户登录", httpMethod = "POST")
    @PostMapping("/login")
    public R login(User user){
        return R.success("登录成功", user);
    }
}

4.5 SpringBoot 启动类

App.java

package cn.uni;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class App {
    public static void main(String[] args) {
        SpringApplication.run(App.class);
    }
}

4.6 运行并测试案例

Swagger 学习笔记 | Swagger 简介 | Springfox 简介 | Springfox 2.9.2 常用注解 | Spring Boot 整合 Swagger2 案例

Java相关栏目本月热门文章