名称解释

在开始使用 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 。

SpringBoot + Swagger + ReDoc 笔记

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 填进去。

SpringBoot + Swagger + ReDoc 笔记

文档效果

SpringBoot + Swagger + ReDoc 笔记

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 笔记

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 不完善之处

相关推荐