SpringBoot + Swagger + ReDoc 笔记

名称解释

在开始使用 Swagger 之前，我们先来了解下几个概念。

名词	释义
Swagger	Swagger 是一个 RESTful 接口规范，现在流行的版本有 2.0 和 3.0 。
OpenAPI	OpenAPI 规范就是之前的 Swagger 规范，只是换了个名字。
swagger.json/swagger.yaml	swagger.json 或 swagger.yaml 是符合 Swagger 规范的接口描述文件。文件名称随意，这里只是举例。
Springfox	Springfox 套件可以为 Spring 系列项目自动生成 swagger.json，还可以集成 Swagger UI。
Swagger UI	Swagger UI 通过解析 swagger.[json/yaml]，来生成在线接口文档。
ReDoc	ReDoc 是另一个 Swagger UI 工具。

Springfox

Springfox 当前有两个主要版本：正式版 2.9.2 和 快照版 3.0.0-SNAPSHOT。下面先介绍正式版的使用，建议读者先试用正式版。

2.9.2

Maven 依赖


<properties>
    <springfox.version>2.9.2</springfox.version>
</properties>

<dependencies>
    <!-- 生成 Swagger 文档 -->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>${springfox.version}</version>
    </dependency>
    <!-- 添加 Springfox Swagger UI 支持 -->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>${springfox.version}</version>
    </dependency>
</dependencies>

编写 Swagger 配置类

在 SpringBoot 启动类同级目录下添加该配置类。
配置类 SwaggerConfig 上添加 @Configuration 注解，是为了让 Spring 识别到这是一个配置类。

package org.qadoc.demo.web;

import com.google.common.base.Predicates;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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 java.util.ArrayList;

/**
 * Swagger 配置类 <br>
 * 创建时间：2019/4/10 15:35<br>
 * @author xxx
 */
@Configuration
public class SwaggerConfig {

  @Bean
  public Docket demoAPI(){
    return new Docket(DocumentationType.SWAGGER_2) //采用 Swagger 2.0 规范
        .select()
        .apis(RequestHandlerSelectors.any()) //所有API接口类都生成文档
        .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))//方法一：不展示 Spring 自带的 error Controller
        //.apis(RequestHandlerSelectors.basePackage("org.qadoc.demo.web.controller"))//方法二：不展示 Spring 自带的 error Controller
        //.paths(Predicates.not(PathSelectors.regex("/error.*")))//方法三（3.0.0不适用）：不展示 Spring 自带的 error Controller
        .paths(PathSelectors.any())
        .build()
        //.pathMapping("/")
        //.directModelSubstitute(LocalDate.class,String.class)
        //.genericModelSubstitutes(ResponseEntity.class)
        .useDefaultResponseMessages(false)
        //.tags(new Tag("tagName","description"))
        .apiInfo(apiInfo())
        ;
  }

  //接口文档基础信息
  private ApiInfo apiInfo(){
    Contact contact = new Contact("","","");
    return new ApiInfo(
        "Demo API 文档",
        "Demo API 文档(Web端）",
        "1.0.0",
        "",
        contact,
        "",
        "",
        new ArrayList<>()
    );
  }

}

启用 Swagger

在 SpringBoot 的启动类上添加 @EnableSwagger2 注解。

package org.qadoc.demo.web;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@SpringBootApplication
@EnableSwagger2
public class DemoWebApplication {

  public static void main(String[] args) {
    SpringApplication.run(DemoWebApplication.class, args);
  }

}

Swagger 文档注解

Swagger 的文档注解有三类：

resource（Controller 类）注解
operation（API 方法）注解
API models（实体类）注解

注解概览

注解	描述
@Api	标记一个类为 Swagger 资源。
@ApiImplicitParam	表示 API Operation 中的单个参数。
@ApiImplicitParams	包装注解，包含多个 @ApiImplicitParam 注解
@ApiModel	提供 Swagger models 的附加信息
@ApiModelProperty	添加和操作 model 属性的数据。
@ApiOperation	描述一个特定路径的 operation（通常是 HTTP 方法）
@ApiParam	为 operation 参数添加额外的 meta-data。
@ApiResponse	描述 operation 可能的响应。
@ApiResponses	包装注解，包含多个 @ApiResponse 注解。
@ResponseHeader	表示响应头。

Resource API 注解

@Api

声明该 API 接口类需要生成文档。

@Api(tags = {"应用健康检查"})
@RestController
@RequestMapping(value = "/healthcheck")
public class HealthCheckController {
    ...
}

属性列表

属性	描述
tags	属性用来对接口进行分组管理。当然你可以添加多个 tag，那么该类下的接口会在这两个分组里出现。

注意事项：

如果没有指定响应的 Content-Type ，springfox 的默认值是 */*。有两种指定方式。

在 Controller 类或方法上的 @RequestMapping 注解中增加 produces 属性值。

@RequestMapping(value = "/healthcheck",produces = MediaType.APPLICATION_JSON_VALUE)

在 Swagger 配置类中指定默认值。

docket
...
    .produces(Sets.newHashSet(MediaType.APPLICATION_JSON_VALUE))
    .consumes(Sets.newHashSet(MediaType.APPLICATION_JSON_VALUE))
...

@ApiIgnore

声明该 API 接口类不需要生成文档。

@ApiIgnore("过时的API")
@ConditionalOnExpression("false")
@RestController
@RequestMapping(value = "/record/xianbank")
public class RecordXianBankController {
    ...
}

Operation 注解

@ApiOperation

用于接口方法上，描述该接口相关信息。

@ApiOperation(
  nickname = "healthCheckUsingGet",
  value = "应用健康检查",
  notes = "用于检查应用是否可以正常访问。",
  produces = MediaType.APPLICATION_JSON_VALUE,
  response = HealthCheckRes.class
)
@GetMapping()
public BaseResult<HealthCheckRes.AppStatus> healthCheck() {
    ...
}

属性列表

属性	描述
nickname	operationID，接口唯一标识
value	接口名称
notes	接口描述信息
produces	响应 Content-Type，示例："application/json, application/xml"
consumes	请求 Content-Type，示例："application/json, application/xml"
response	response body Model，响应体结构及单个字段示例

@ApiImplicitParams 和 @ApiImplicitParam

描述接口的请求信息。

@ApiOperation(
    ...
)
//请求参数
@ApiImplicitParams({
    @ApiImplicitParam(
        name = "id",value = "用户 ID",paramType = ParamType.PATH,required = true, dataType = "Long", example = "823928392"
    )
})
@DeleteMapping("/path/{id}")
public BaseResult<SwaggerTestRes> testSwaggerWithPath(@PathVariable Long id){
  logger.info(id.toString());
  SwaggerTestRes res = new SwaggerTestRes();
  res.setId(id);
  res.setName("刘备");
  res.setAge(180);
  res.setSex('0');
  res.setAddress("蜀山大地");
  return new BaseResult(res);
}

@ApiImplicitParam 属性列表

属性	类型	描述
name	String	参数名称。
value	String	参数描述。
paramType	String	请求参数类型，String类型，枚举值包括：path、query、body、header、form。
required	boolean	是否必传，true 为必传，默认为 false。
dataType	String	参数数据类型，一般为类名。
dataTypeClass	Class<?>	参数数据类型，值为 Xxx.class。
example	String	参数示例，针对非 Body 类型的参数。
examples	Example	参数示例，针对 Body 类型的参数。

详细例子，请看本节后面的完整示例。

@ApiResponses 和 @ApiResponse

描述接口的响应信息。

@ApiOperation(
    ...
)
//请求参数
@ApiImplicitParams({
    ...
})
//响应
@ApiResponses({
    //code重复的情况下，第一个声明的生效。
    @ApiResponse(code = 200,message = "成功"
        //examples 属性，springfox 2.x.x 不支持，需要 3.0.0及以上
        ,examples = @Example(
            value = {
                @ExampleProperty(mediaType = "一个示例",value = "{\n" +
                    "  \"code\": \"0000\",\n" +
                    "  \"data\": {\n" +
                    "    \"address\": \"马尔代夫\",\n" +
                    "    \"age\": 66,\n" +
                    "    \"id\": 888888,\n" +
                    "    \"name\": \"小虾米\",\n" +
                    "    \"sex\": 0\n" +
                    "  },\n" +
                    "  \"message\": \"OK\"\n" +
                    "}")}
        )
    ),
    @ApiResponse(code = 400,message = "你一定是干坏事了")
})
@DeleteMapping("/path/{id}")
public BaseResult<SwaggerTestRes> testSwaggerWithPath(@PathVariable Long id){
  logger.info(id.toString());
  SwaggerTestRes res = new SwaggerTestRes();
  res.setId(id);
  res.setName("刘备");
  res.setAge(180);
  res.setSex('0');
  res.setAddress("蜀山大地");
  return new BaseResult(res);
}

属性	类型	描述
code	String	接口响应状态码。
message	String	接口响应状态信息。
examples	Example	响应示例，mediaType 为示例名称，value 为示例值。

Model 注解

@ApiModel

描述 Model（实体类）。

@ApiModel(value = "SwaggerTestRes",description = "Swagger Demo 演示实体类")
public class SwaggerTestRes {

  ...

}

属性	类型	描述
value	String	Model 名称，一般为实体类类名。
description	String	Model 描述信息。

@ApiModelProperty

描述 Model 属性。

@ApiModel(value = "SwaggerTestRes",description = "Swagger Demo 演示实体类")
public class SwaggerTestRes {

  @ApiModelProperty(value = "用户 ID",example = "23829832983")
  private Long id;
  @ApiModelProperty(value = "姓名",example = "老顽童")
  private String name;
  @ApiModelProperty(value = "年龄",example = "199",allowableValues = "range[0,200]")
  private int age;
  @ApiModelProperty(value = "性别。0：男，1：女。",example = "0",allowableValues = "0,1")
  private char sex;
  @ApiModelProperty(value = "家庭住址",example = "中国浙江省杭州市滨江区上峰电商产业园")
  private String address;

  ...

}

属性	类型	描述
value	String	属性描述。
example	String	属性示例。
allowableValues	String	限制参数值的范围。有三种限制类型。第一种，用英文逗号分隔的枚举值，如：`first, second, third`。第二种，固定范围，如：`range[1, 5]`、 `range(1, 5)`、`range[1, 5)`。第三种，接受无穷大的值范围，如：`range[1, infinity]`、`range[-infinity, 100]`

如果出现 @ApiModelProperty throwing NumberFormatException if example value is not set 错误，修改 pom.xml 为：

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
    <exclusions>
        <exclusion>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-annotations</artifactId>
        </exclusion>
        <exclusion>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-models</artifactId>
        </exclusion>
    </exclusions>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-annotations</artifactId>
    <version>1.5.21</version>
</dependency>
<dependency>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-models</artifactId>
    <version>1.5.21</version>
</dependency>

Swagger 注解完整示例

实体类

package org.qadoc.demo.web.pojo.base;

import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.ObjectMapper;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import org.apache.commons.lang3.StringUtils;

import java.io.Serializable;

/**
 * Rest 接口返回值<br>
 * 作者： xxx
 */
@ApiModel(value = "BaseResult",description = "接口返回值统一定义实体")
public class BaseResult<T> implements Serializable {

  private static final long serialVersionUID = -814929216218701299L;

  @ApiModelProperty(value = "状态码",example = "0000")
  private String code;
  @ApiModelProperty(value = "消息",example = "OK")
  private String message;
  @ApiModelProperty(value = "接口响应数据")
  private T data;

  ...

}

package org.qadoc.demo.web.swagger.model.res;

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

/**
 * Swagger 测试：接口返回值实体 <br>
 * 创建时间：2019/4/11 18:44<br>
 * 作者：xxx
 */
@ApiModel
public class SwaggerTestRes {

  @ApiModelProperty(value = "用户 ID",example = "23829832983")
  private Long id;
  @ApiModelProperty(value = "姓名",example = "老顽童")
  private String name;
  @ApiModelProperty(value = "年龄",example = "199",allowableValues = "range[0,200]")
  private int age;
  @ApiModelProperty(value = "性别。0：男，1：女。",example = "0",allowableValues = "0,1")
  private char sex;
  @ApiModelProperty(value = "家庭住址",example = "中国浙江省xxx产业园")
  private String address;

  public Long getId() {
    return id;
  }

  public void setId(Long id) {
    this.id = id;
  }

  public String getName() {
    return name;
  }

  public void setName(String name) {
    this.name = name;
  }

  public int getAge() {
    return age;
  }

  public void setAge(int age) {
    this.age = age;
  }

  public char getSex() {
    return sex;
  }

  public void setSex(char sex) {
    this.sex = sex;
  }

  public String getAddress() {
    return address;
  }

  public void setAddress(String address) {
    this.address = address;
  }

}

Controller 类

package org.qadoc.demo.web.controller;

import org.qadoc.demo.web.constant.ParamType;
import org.qadoc.demo.web.pojo.base.BaseResult;
import org.qadoc.demo.web.swagger.model.res.SwaggerTestRes;
import io.swagger.annotations.*;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.*;

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

/**
 * Swagger 测试 API 类 <br>
 * 创建时间：2019/4/11 18:32<br>
 * 作者：xxx
 */
@Api(tags = {"Swagger 测试"})
@RestController
@RequestMapping(value = "/swagger/test")
public class SwaggerTestController {

  private static final Logger logger = LoggerFactory.getLogger(SwaggerTestController.class);


  @ApiOperation(
      value = "Path 参数测试",
      notes = "根据用户 ID 删除用户。",
      produces = MediaType.APPLICATION_JSON_VALUE
  )
  //请求参数
  @ApiImplicitParams({
      @ApiImplicitParam(
          name = "id",value = "用户 ID",paramType = ParamType.PATH,required = true, dataType = "Long", example = "823928392"
      )
  })
  //响应
  @ApiResponses({
      //code重复的情况下，第一个声明的生效。
      @ApiResponse(code = 200,message = "成功"
          //springfox 2.x.x 不支持，需要 3.0.0及以上
          ,examples = @Example(
              value = {
                  @ExampleProperty(mediaType = "一个示例",value = "{\n" +
                      "  \"code\": \"0000\",\n" +
                      "  \"data\": {\n" +
                      "    \"address\": \"马尔代夫\",\n" +
                      "    \"age\": 66,\n" +
                      "    \"id\": 888888,\n" +
                      "    \"name\": \"小虾米\",\n" +
                      "    \"sex\": 0\n" +
                      "  },\n" +
                      "  \"message\": \"OK\"\n" +
                      "}")}
          )
      ),
      @ApiResponse(code = 400,message = "你一定是干坏事了")
  })
  @DeleteMapping("/path/{id}")
  public BaseResult<SwaggerTestRes> testSwaggerWithPath(@PathVariable Long id){
    logger.info(id.toString());
    SwaggerTestRes res = new SwaggerTestRes();
    res.setId(id);
    res.setName("刘备");
    res.setAge(180);
    res.setSex('0');
    res.setAddress("蜀山大地");
    return new BaseResult(res);
  }

  @ApiOperation(
      value = "Query 参数测试",
      notes = "根据用户姓名和性别查询用户列表。",
      produces = MediaType.APPLICATION_JSON_VALUE
  )
  //请求参数
  @ApiImplicitParams({
      @ApiImplicitParam(
          name = "name",value = "用户姓名",paramType = ParamType.QUERY,required = true, dataType = "String", example = "成龙"
      ),
      @ApiImplicitParam(
          name = "sex",value = "用户性别",paramType = ParamType.QUERY, dataType = "String", example = "0"
      )
  })
  //响应
  @ApiResponses({
      //code重复的情况下，第一个声明的生效。
      @ApiResponse(code = 200,message = "成功"
          //springfox 2.x.x 不支持，需要 3.0.0及以上
          ,examples = @Example(value = {
              @ExampleProperty(mediaType = "名字中有JSON",value = "{\n" +
                  "  \"code\": \"0000\",\n" +
                  "  \"data\": [{\n" +
                  "    \"address\": \"有JSON王国\",\n" +
                  "    \"age\": 88,\n" +
                  "    \"id\": 2353534,\n" +
                  "    \"name\": \"蜘蛛侠\",\n" +
                  "    \"sex\": 0\n" +
                  "  }],\n" +
                  "  \"message\": \"OK\"\n" +
                  "}"),
              @ExampleProperty(mediaType = "名字中无JS0N",value = "{\n" +
                  "  \"code\": \"0000\",\n" +
                  "  \"data\": [{\n" +
                  "    \"address\": \"无JSON王国\",\n" +
                  "    \"age\": 99,\n" +
                  "    \"id\": 673423,\n" +
                  "    \"name\": \"蝙蝠侠\",\n" +
                  "    \"sex\": 0\n" +
                  "  }],\n" +
                  "  \"message\": \"OK\"\n" +
                  "}")}
      )
      )
  })
  @GetMapping("/query")
  public BaseResult<List<SwaggerTestRes>> testSwaggerWithQuery(@RequestParam String name, @RequestParam(required = false) char sex){
    SwaggerTestRes res1 = new SwaggerTestRes();
    res1.setId(23923842L);
    res1.setName("张成龙");
    res1.setSex('0');
    res1.setAge(26);
    res1.setAddress("火星殖民地A区76街道");
    SwaggerTestRes res2 = new SwaggerTestRes();
    res2.setId(92839427947L);
    res2.setName("成龙龙");
    res2.setSex('1');
    res2.setAge(24);
    res2.setAddress("小行星带阿尔法北方殖民地872号");
    List<SwaggerTestRes> list = new ArrayList<>();
    list.add(res1);
    list.add(res2);
    return new BaseResult(list);
  }


  @ApiOperation(
      value = "Form 参数测试",
      notes = "登录XX后台。",
      //实际三种都支持： application/x-www-form-urlencoded, multipart/form-data , queryParam
      consumes = MediaType.APPLICATION_FORM_URLENCODED_VALUE,
      produces = MediaType.APPLICATION_JSON_VALUE
  )
  //请求参数
  @ApiImplicitParams({
      @ApiImplicitParam(
          name = "username",value = "用户名",paramType = ParamType.FORM,required = true, dataType = "String", example = "18868871111"
      ),
      @ApiImplicitParam(
          name = "password",value = "密码",paramType = ParamType.FORM, required = true,dataType = "String", example = "123456"
      )
  })
  @PostMapping("/form")
  public BaseResult<String> testSwaggerWithForm(String username,String password){
    BaseResult<String> result = new BaseResult<>();
    result.setData(username);
    return result;
  }

  @ApiOperation(
      value = "JSON 参数测试",
      notes = "新增一个用户。",
      consumes = MediaType.APPLICATION_JSON_VALUE,
      produces = MediaType.APPLICATION_JSON_VALUE
  )
  //请求参数
  @ApiImplicitParams({
      @ApiImplicitParam(
          name = "user",value = "用户信息",paramType = ParamType.BODY,required = true, dataType = "SwaggerTestRes", examples =
          @Example(value = {
              @ExampleProperty(mediaType = "示例",value = "{\n" +
                  "\"address\": \"花果山水帘洞\",\n" +
                  "\"age\": 500,\n" +
                  "\"id\": 66666666,\n" +
                  "\"name\": \"孙悟空\",\n" +
                  "\"sex\": 0\n" +
                  "}")
          })
      )
  })
  @PostMapping("/body")
  public BaseResult<SwaggerTestRes> testSwaggerWithJSON(@RequestBody SwaggerTestRes user){
    return new BaseResult(user);
  }

}

3.0.0-SNAPSHOT

Maven 依赖

<properties>
    <springfox.version>3.0.0-SNAPSHOT</springfox.version>
</properties>

<repositories>
    <repository>
        <id>jcenter-snapshots</id>
        <name>jcenter</name>
        <url>http://oss.jfrog.org/artifactory/oss-snapshot-local/</url>
    </repository>
</repositories>

<dependencies>

    <dependency>
        <groupId>org.springframework.integration</groupId>
        <artifactId>spring-integration-http</artifactId>
    </dependency>
    <!-- Swagger2 -->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>${springfox.version}</version>
    </dependency>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>${springfox.version}</version>
    </dependency>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-spring-webmvc</artifactId>
        <version>${springfox.version}</version>
    </dependency>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-spring-integration-webmvc</artifactId>
        <version>${springfox.version}</version>
    </dependency>

    <!-- 笔者在 Swagger 配置类时用到，可以不引入 -->
    <dependency>
        <groupId>com.google.guava</groupId>
        <artifactId>guava</artifactId>
        <version>27.1-jre</version>
    </dependency>

</dependencies>

启用 Swagger

在 SpringBoot 的启动类上添加 @EnableSwagger2WebMvc 注解。

和 2.9.2 版本的区别

Maven 依赖包不同。
启用 Swagger 的注解不同。
修复了 @ApiResponse 中 examples 属性没有生效的 bug 。
修复了 @ApiModelProperty throwing NumberFormatException if example value is not set 的 Bug。

访问 Swagger UI

启动 SpringBoot 应用。
访问 http://ip:port/swagger-ui.html 。

ReDoc

获取 swagger.json 的接口

启动 SpringBoot 应用后，得到 swagger.json 的接口地址 http://ip:port/v2/api-docs。

配置 Nginx 代理

这里使用 Nginx 做反向代理，是为了解决 ReDoc 的跨域问题。

server
{
    listen 80;
    listen 443;
    server_name doc.xxx.cn;

    ssl on;
    ssl_certificate   cert/xxx.cn/cert.xxx.cn.crt;
    ssl_certificate_key  cert/xxx.cn/cert.xxx.cn.key;
    ssl_session_timeout 5m;
    ssl_ciphers HIGH:!aNULL:!MD5;
    ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
    ssl_prefer_server_ciphers on;

    add_header Access-Control-Allow-Origin *; //必须加这句，否则访问时会有跨域问题
    index index.html index.htm;
      root /home/wwwroot/doc.xxx.cn/;

    access_log      logs/doc.xxx.cn.access.log;
    error_log       logs/doc.xxx.cn.error.log;
    
    location ^~ /swagger/mocklab {
      proxy_pass  http://10.200.4.26:9101/v2/api-docs;
    }

}

访问在线接口文档

方法一：自己写个静态 HTML 页面，放到内网服务器上。

<!DOCTYPE html>
<html>
  <head>
    <title>ReDoc</title>
    <!-- needed for adaptive design -->
    <meta charset="utf-8"/>
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">

    <!--
    ReDoc doesn't change outer page styles
    -->
    <style>
      body {
        margin: 0;
        padding: 0;
      }
    </style>
  </head>
  <body>
    <!-- 这里填写 swagger 文件访问地址或接口访问地址 -->
    <redoc spec-url='https://doc.xxx.cn/swagger/mocklab' untrustedSpec=true></redoc>
    <script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"> </script>
  </body>
</html>

方法二：使用官方的在线交互 Demo，把自己的接口地址 https://doc.xxx.cn/swagger/mocklab 填进去。

文档效果

ReDoc 不完善之处

当请求 Content-Type 为 application/json 和 application/x-www-form-urlencoded 时，不展示 @ApiImplicitParam example 属性(x-example 节点) 的值。
当请求 Content-Type 为 application/json 时，不展示 @ApiImplicitParam examples 属性(x-examples 节点) 的值。
当 @ApiResponse 下 @ExampleProperty 的 mediaType 属性值中包含 json 字符（不区分大小写）时，页面展示的 JSON 没有转义，如图：

SpringBoot + Swagger + ReDoc 笔记

名称解释

Springfox

2.9.2

Maven 依赖

编写 Swagger 配置类

启用 Swagger

Swagger 文档注解

Resource API 注解

Operation 注解

Model 注解

Swagger 注解完整示例

3.0.0-SNAPSHOT

Maven 依赖

启用 Swagger

和 2.9.2 版本的区别

访问 Swagger UI

ReDoc

获取 swagger.json 的接口

配置 Nginx 代理

访问在线接口文档

文档效果

ReDoc 不完善之处

千里云飞

引用和评论

Windows SSH 免密登录详解

AES 加密和解密demo

Thymeleaf的使用

Spring Boot起步，CRUD、错误处理与宝塔部署

实现 Angular 程序处理进度条

Spring boot连接Minio实现文件的上传以及下载

记录下解决自定义 Feign 调用，响应content-type 格式不正确导致的解析错误