Swagger 与 SpringBoot 整合

原创

ch3nnn 2022-07-19 09:56:43 博主文章分类：Java ©著作权

©著作权归作者所有：来自51CTO博客作者ch3nnn的原创作品，请联系作者获取转载授权，否则将追究法律责任

Swagger 使用

Swagger 有什么用？

Swagger 是一个流行的API开发框架，这个框架以“开放API声明” （OpenAPI Specification，OAS）为基础，对整个 API 的开发周期都提供了相应的解决方案，是一个非常庞大的项目（包括设计、编码和测试，几乎支持所有语言）。

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

总体目标是使客户端和文件系统作为服务器以同样的速度来更新。

文件的方法，参数和模型紧密集成到服务器端的代码，允许 API 来始终保持同步。 Swagger 让部署管理和使用功能强大的 API 从未如此简单。

SpringBoot 与 Swagger2

由于 Java 的强大的注解功能，我们使用 SpringBoot 来结合 Swagger2 ，在使用起来非常简单.

github swagger

第一步：新建 SpringBoot 项目，引入依赖.

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.7.0</version>
</dependency>

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.7.0</version>
</dependency>

上面两个依赖的作用：

springfox-swagger2 依然是依赖 OSA 规范文档，也就是一个描述 API 的 json 文件，而这个组件的功能就是帮助我们自动生成这个 json 文件

SpringFox 大致原理：

springfox的大致原理就是，在项目启动的过程中，Spring 上下文在初始化的过程，框架自动根据配置加载一些 Swagger 相关的
bean 到当前的上下文中，并自动扫描系统中可能需要生成 API 文档那些类，并生成相应的信息缓存起来。如果项目MVC控制层用的是
SpringMvc 那么会自动扫描所有 Controller 类，并生成对应的文档描述数据.
该数据是json格式，通过路径：项目地址 /v2/api-docs可以访问到该数据，然后
SwaggerUI根据这份数据生成相应的文档描述界面。因为我们能拿到这份数据，所以我们也可以生成自己的页面。

springfox-swagger-ui 就是将这个 json 文件解析出来，用一种更友好的方式呈现出来。

由于 Spring 的流行，Marty Pitt 编写了一个基于 Spring 的组件 swagger-springmvc，用于将
Swagger 集成到 SpringMVC 中来。

第二步：创建 API

@RestController
public class UserController {

    @RequestMapping("/hello",method = RequestMethod.GET)
    public String hello(){
        return "hello";
    }

}

配置 Swagger2

现在 Swagger2 还不能为我们生成 API 文档，因为我们还没有对它进行配置。

我们需要创建一个配置类，进行如下配置：

@Configuration
@EnableSwagger2
public class SwaggerConfig{

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("cn.ch3nnn.adminblog"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("基于Spring Boot 开发Django 后台管理系统")
                .description("rest api 文档构建利器")
               .termsOfServiceUrl(")
                .contact("itguang")
                .version("1.0")
                .build();
    }

}

springfox 为我们提供了一个 Docket（摘要的意思）类，我们需要把它做成一个 Bean 注入到 spring 中。显然，我们需要一个配置文件，并通过一种方式（显然它会是一个注解）告诉程序，这是一个 Swagger 配置文件。

springfox 允许我们将信息组合成一个 ApiInfo 的类，作为构造参数传给 Docket（当然也可以不构造这个类，而直接使用 Null，但是你的这个 API 就太 low 了）。

搞定

现在我们要做的配置已经能满足一个生成 API 文档的基本要求了，让我们启动项目，访问
http://localhost/swagger-ui.html

会看到如下界面:

Swagger 与 SpringBoot 整合_restful

这是 Swagger-ui 为我们生成的界面.

Swagger2 注解使用
接下来我们就要好好研究下 springfox-swagger2 给我们提供的注解了.

我们新建一个 Controller，用来对 User 类进行增删改查常用操作。

UserController.java

package com.didispace.demo;

import java.util.ArrayList;
import java.util.List;

import javax.validation.Valid;

import org.springframework.web.bind.annotation.*;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import springfox.documentation.annotations.ApiIgnore;

@Api(tags = "用户管理")
@RestController
public class UserController {

    @ApiOperation("创建用户")
    @PostMapping("/users")
    public User create(@RequestBody @Valid User user) {
        return user;
    }

    @ApiOperation("用户详情")
    @GetMapping("/users/{id}")
    public User findById(@PathVariable Long id) {
        return new User("bbb", 21, "上海", "aaa@bbb.com");
    }

    @ApiOperation("用户列表")
    @GetMapping("/users")
    public List<User> list(@ApiParam("查看第几页") @RequestParam int pageIndex,
        @ApiParam("每页多少条") @RequestParam int pageSize) {
        List<User> result = new ArrayList<>();
        result.add(new User("aaa", 50, "北京", "aaa@ccc.com"));
        result.add(new User("bbb", 21, "广州", "aaa@ddd.com"));
        return result;
    }

    @ApiIgnore
    @DeleteMapping("/users/{id}")
    public String deleteById(@PathVariable Long id) {
        return "delete user : " + id;
    }

}

可以看到我们在 Controller 上使用了 @Api(tags = “用户管理”)注解，在方法上使用了 @ApiOperation(“创建用户”)注解。

但是我们如果想选择性的忽略某个字段，而不是把 User 类中的所有字段暴露出去呢?别着急，我们可以使用另一个注解：@ApiModelProperty(hidden = true)。此注解可以作用在字段或者方法上，只要 hidden 属性为 true ，该字段或者方法就不会被生成 API 文档。

User.java

package com.didispace.demo;

import javax.validation.constraints.*;

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

@Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel("用户基本信息")
public class User {

    @ApiModelProperty("姓名")
    @Size(max = 20)
    private String name;
    
    @ApiModelProperty(hidden = true)
    private String password;

    @ApiModelProperty("年龄")
    @Max(150)
    @Min(1)
    private Integer age;
    
    @NotNull
    private String address;
    
    @Pattern(regexp = "^[a-zA-Z0-9_-]+@[a-zA-Z0-9_-]+(\\.[a-zA-Z0-9_-]+)+$")
    private String email;

}

我们有意忽略了 password 字段，再次刷新浏览器，会看到：
确实 password 字段不见了。

常用注解说明：

通过上面的了解，我们大概已经会使用 Swagger2 了，但我们只介绍了一些简单常用的注解。下面我们系统的总结一下：

Swagger2 基本使用(重点加粗显示)：

@Api：描述类/接口的主要用途

@ApiOperation：描述方法用途

@ApiImplicitParam：描述方法的参数

@ApiImplicitParams：描述方法的参数(Multi-Params)

可以在上面 创建用户的方法上添加 @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")试试看.

@ApiParam：请求属性

@ApiIgnore：忽略某类/方法/参数的文档

注意与 @ApiModelProperty(hidden = true)不同， @ApiIgnore 不能用在模型数据上
@ApiResponse：响应配置

如 @ApiResponse(code = 400, message = "无效的用户信息") ，注意这只是在 生成的 Swagger 文档上有效，不要和实际的客户端调用搞混了.


通常我们都是统一JSON返回，用不到这个注解
@ApiResponses：响应集配置

@ResponseHeader：响应头设置

例如: @ResponseHeader(name="head1",description="response head conf")
@ApiModel：标识请求/相应模型

@ApiModelProperty：添加和操作模型属性的数据