Spring Boot 2.X集成 Swagger2 开发 API 文档（在线+离线）

点击上方蓝色字体，选择“标星公众号”

优质文章，第一时间送达

上一篇：这300G的Java资料是我师傅当年给我的，免费分享给大家

下一篇：昨天分享资料不小心把百度网盘深处的秘密泄露了

作者：朝雾轻寒 来源：开源中国：

http://suo.im/6iDzqd

前言

相信很多后端开发在项目中都会碰到要写 api 文档，不管是给前端、移动端等提供更好的对接，还是以后为了以后交接方便，都会要求写 api 文档。

而手写 api 文档的话有诸多痛点：

• 文档更新的时候，需要再次发送给对接人

• 接口太对，手写文档很难管理

• 接口返回的结果不明确

• 不能直接在线测试接口，通常需要使用工具，如 postman 等

Swagger 就很好的解决了这个问题。

Swagger 简介

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。

官网：https://swagger.io

Swagger 使用

1.相关依赖

<!--swagger2 -->
    <dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger2</artifactId>
      <version>2.9.2</version>
    </dependency>
    <dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger-ui</artifactId>
      <version>2.9.2</version>
    </dependency>

2.Swagger 配置类

@Configuration
@EnableSwagger2
public class SwaggerConfig {
  @Bean
    public Docket buildDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(buildApiInf()) //将api的元信息设置为包含在json resourcelisting响应中
        //.host("127.0.0.1:8080") //设置ip和端口，或者域名
        .select() //启动用于api选择的生成器
        //.apis(RequestHandlerSelectors.any())
        .apis(RequestHandlerSelectors.basePackage("cn.zwqh.springboot.controller"))//指定controller路径
        .paths(PathSelectors.any()).build();
    }

    private ApiInfo buildApiInf() {
      
        Contact contact=new Contact("朝雾轻寒","https://www.zwqh.top/","zwqh@clover1314.com");
        return new ApiInfoBuilder()
        .title("Swagger Demo Restful API Docs")//文档标题
        .description("Swagger 示例 Restful Api 文档")//文档描述
        .contact(contact)//联系人
        .version("1.0")//版本号
        //.license("")//更新此API的许可证信息
        //.licenseUrl("")//更新此API的许可证Url
        //.termsOfServiceUrl("")//更新服务条款URL
        .build();

    }
}

3.Spring MVC 相关配置

@Configuration
public class WebMvcConfig extends WebMvcConfigurationSupport {
  /**
   * 静态资源配置(默认)
   */
  @Override
  public void addResourceHandlers(ResourceHandlerRegistry registry) {
    registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");// 静态资源路径
    registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
    registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    super.addResourceHandlers(registry);
  }


}

如果不添加此静态资源配置会报错，找不到相关路径

4.Model 中使用 Swagger 注解

@ApiModel(value = "UserEntity", description = "用户对象")
public class UserEntity implements Serializable{

  /**
   *
   */
  private static final long serialVersionUID = 5237730257103305078L;
  @ApiModelProperty(value ="用户id",name="id",dataType="Long",required = false,example = "1",hidden = false )
  private Long id;
  @ApiModelProperty(value ="用户名",name="userName",dataType="String",required = false,example = "关羽" )
  private String userName;
  @ApiModelProperty(value ="用户性别",name="userSex",dataType="String",required = false,example = "男" )
  private String userSex;

  public Long getId() {
    return id;
  }

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

  public String getUserName() {
    return userName;
  }

  public void setUserName(String userName) {
    this.userName = userName;
  }

  public String getUserSex() {
    return userSex;
  }

  public void setUserSex(String userSex) {
    this.userSex = userSex;
  }

}

5. Controller 中使用 Swagger 注解

@RestController
@RequestMapping("/api")
@Api(tags = { "接口分组1", "接口分组2" })
public class ApiController {

  @Autowired
  private UserDao userDao;

  @GetMapping("/getAllUser")
  @ApiOperation(value = "获取所有用户", notes = "", httpMethod = "GET", tags = "接口分组3")
  public List<UserEntity> getAll() {
    return userDao.getAll();
  }

  @GetMapping("/getUserById")
  @ApiOperation(value = "根据id获取用户", notes = "id必传", httpMethod = "GET")
  @ApiImplicitParam(name = "id", value = "用户id",example = "1", required = true, dataType = "long", paramType = "query")
  public UserEntity getOne(Long id) {
    return userDao.getOne(id);
  }

  @PostMapping("/getUserByNameAndSex")
  @ApiOperation(value = "根据name和sex获取用户", notes = "", httpMethod = "POST")
  @ApiImplicitParams({
      @ApiImplicitParam(name = "userName", value = "用户名", example = "关羽", required = true, dataType = "string", paramType = "query"),
      @ApiImplicitParam(name = "userSex", value = "用户性别", example = "男", required = true, dataType = "string", paramType = "query") })
  public UserEntity getUserByNameAndSex(String userName, String userSex) {
    return userDao.getUserByNameAndSex(userName, userSex);
  }

  @PostMapping("/insertUser")
  @ApiOperation(value = "新增用户", notes = "传json，数据放body", httpMethod = "POST")
  @ApiImplicitParams({
      @ApiImplicitParam(name = "body", value = "用户对象json", example = "{userName:'朝雾轻寒',userSex:'男'}", required = true) })
  public String insertUser(@RequestBody String body) {
    System.out.println(body);
    UserEntity user = JSON.parseObject(body, UserEntity.class);
    userDao.insertUser(user);
    return "{code:0,msg:'success'}";
  }

  @PostMapping("/updateUser")
  @ApiOperation(value = "修改用户", notes = "传json，数据放body", httpMethod = "POST")
  @ApiImplicitParams({
      @ApiImplicitParam(name = "body", value = "用户对象json", example = "{id:23,userName:'朝雾轻寒',userSex:'女'}", required = true) })
  public String updateUser(@RequestBody String body) {
    System.out.println(body);
    UserEntity user = JSON.parseObject(body, UserEntity.class);
    userDao.updateUser(user);
    return "{code:0,msg:'success'}";
  }

  @PostMapping("/deleteUser")
  @ApiOperation(value = "删除用户", notes = "id必传", httpMethod = "POST")
  public String deleteUser(@ApiParam(name = "id", value = "用户id", required = true) Long id) {
    userDao.deleteUser(id);
    return "{code:0,msg:'success'}";
  }
}

6.测试

访问 http://127.0.0.1:8080/swagger-ui.html 进行接口在线测试

Swagger 常用注解

1.@Api

用于类，表示标识这个类是swagger的资源。属性如下：

• tags 表示说明，tags如果有多个值，会生成多个列表

• value 表示说明，可以使用tags替代

2.@ApiOperation

用于方法，表示一个http请求的操作。属性如下：

• value 用于方法描述

• notes 用于提示内容

• tags 用于API文档控制的标记列表，视情况而用，可以进行独立分组

3.@ApiParam

用于方法、参数、字段说明；表示对参数的添加元数据。

• name 参数名

• value 参数说明

• required 是否必填

4.@ApiModel

用于类，表示对类进行说明，用于参数用实体类接受。

• value 对象名

• description 描述

5.@ApiModelProperty

用于方法、字段，表示对model属性的说明或者数据操作更改。

• value 字段说明

• name 重写属性名

• dataType 重写属性数据类型

• required 是否必填

• example 举例说明

• hidden 隐藏

6.@ApiIgnore

用于类、方法、方法参数，表示这个方法或者类被忽略，不在swagger-ui.html上显示。

7.@ApiImplicitParam

用于方法，表示单独的请求参数。

• name 参数名

• value 参数说明

• dataType 数据类型

• paramType 参数类型

• example 举例说明

8.@ApiImplicitParams

用于方法，包含多个 @ApiImplicitParam。

9.@ApiResponses @ApiResponse

用于类或者方法，描述操作的可能响应。

• code 响应的HTTP状态代码

• message 响应附带的可读消息

10.@ResponseHeader

用于方法，响应头设置。

• name 响应头名称

• description 头描述

• response 默认响应类 void

• responseContainer 参考ApiOperation中配置

Swagger 导出离线 api 文档

1.导出 AsciiDocs、Markdown、Confluence 格式文档

添加依赖

<!-- swagger2markup 相关依赖 -->
    <dependency>
      <groupId>io.github.swagger2markup</groupId>
      <artifactId>swagger2markup</artifactId>
      <version>1.3.3</version>
    </dependency>

转换工具类

public class SwaggerUtils {

  private static final String url = "http://127.0.0.1:8080/v2/api-docs";
  /**
   * 生成AsciiDocs格式文档
   * @throws MalformedURLException
   */
  public static void generateAsciiDocs() throws MalformedURLException {
    Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
        .withMarkupLanguage(MarkupLanguage.ASCIIDOC)
        .withOutputLanguage(Language.ZH)
        .withPathsGroupedBy(GroupBy.TAGS)
        .withGeneratedExamples()
        .withoutInlineSchema().build();

    Swagger2MarkupConverter.from(new URL(url))
        .withConfig(config)
        .build()
        .toFolder(Paths.get("./docs/asciidoc/generated"));
  }
  /**
   * 生成AsciiDocs格式文档,并汇总成一个文件
   * @throws MalformedURLException
   */
  public static void generateAsciiDocsToFile() throws MalformedURLException {
    Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withMarkupLanguage(MarkupLanguage.ASCIIDOC)
                .withOutputLanguage(Language.ZH)
                .withPathsGroupedBy(GroupBy.TAGS)
                .withGeneratedExamples()
                .withoutInlineSchema()
                .build();

        Swagger2MarkupConverter.from(new URL(url))
                .withConfig(config)
                .build()
                .toFile(Paths.get("./docs/asciidoc/generated/all"));
  }
  
  /**
   * 生成Markdown格式文档
   * @throws MalformedURLException
   */
  public static void generateMarkdownDocs() throws MalformedURLException {
    Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withMarkupLanguage(MarkupLanguage.MARKDOWN)
                .withOutputLanguage(Language.ZH)
                .withPathsGroupedBy(GroupBy.TAGS)
                .withGeneratedExamples()
                .withoutInlineSchema()
                .build();

        Swagger2MarkupConverter.from(new URL(url))
                .withConfig(config)
                .build()
                .toFolder(Paths.get("./docs/markdown/generated"));
  }
  /**
   * 生成Markdown格式文档,并汇总成一个文件
   * @throws MalformedURLException
   */
  public static void generateMarkdownDocsToFile() throws MalformedURLException {
    Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withMarkupLanguage(MarkupLanguage.MARKDOWN)
                .withOutputLanguage(Language.ZH)
                .withPathsGroupedBy(GroupBy.TAGS)
                .withGeneratedExamples()
                .withoutInlineSchema()
                .build();

        Swagger2MarkupConverter.from(new URL(url))
                .withConfig(config)
                .build()
                .toFile(Paths.get("./docs/markdown/generated/all"));
  }
  
  /**
   * 生成Confluence格式文档
   * @throws MalformedURLException
   */
  public static void generateConfluenceDocs() throws MalformedURLException {
    Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withMarkupLanguage(MarkupLanguage.CONFLUENCE_MARKUP)
                .withOutputLanguage(Language.ZH)
                .withPathsGroupedBy(GroupBy.TAGS)
                .withGeneratedExamples()
                .withoutInlineSchema()
                .build();

        Swagger2MarkupConverter.from(new URL(url))
                .withConfig(config)
                .build()
                .toFolder(Paths.get("./docs/confluence/generated"));
  }
  
  /**
   * 生成Confluence格式文档,并汇总成一个文件
   * @throws MalformedURLException
   */
  public static void generateConfluenceDocsToFile() throws MalformedURLException {
    Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withMarkupLanguage(MarkupLanguage.CONFLUENCE_MARKUP)
                .withOutputLanguage(Language.ZH)
                .withPathsGroupedBy(GroupBy.TAGS)
                .withGeneratedExamples()
                .withoutInlineSchema()
                .build();

        Swagger2MarkupConverter.from(new URL(url))
                .withConfig(config)
                .build()
                .toFile(Paths.get("./docs/confluence/generated/all"));
  }
  
  
}

使用测试 Controller

@RestController
@RequestMapping("/export")
@ApiIgnore
public class ExportController {

  
  @RequestMapping("/ascii")
  public String exportAscii() throws MalformedURLException{
    SwaggerUtils.generateAsciiDocs();
    return "success";
  }
  
  @RequestMapping("/asciiToFile")
  public String asciiToFile() throws MalformedURLException{
    SwaggerUtils.generateAsciiDocsToFile();
    return "success";
  }
  
  @RequestMapping("/markdown")
  public String exportMarkdown() throws MalformedURLException{
    SwaggerUtils.generateMarkdownDocs();
    return "success";
  }
  
  @RequestMapping("/markdownToFile")
  public String exportMarkdownToFile() throws MalformedURLException{
    SwaggerUtils.generateMarkdownDocsToFile();
    return "success";
  }
  
  @RequestMapping("/confluence")
  public String confluence() throws MalformedURLException{
    SwaggerUtils.generateConfluenceDocs();
    return "success";
  }
  
  @RequestMapping("/confluenceToFile")
  public String confluenceToFile() throws MalformedURLException{
    SwaggerUtils.generateConfluenceDocsToFile();
    return "success";
  }
}

2.导出 html、pdf、xml 格式

添加依赖

<!--离线文档 -->
    <dependency>
      <groupId>org.springframework.restdocs</groupId>
      <artifactId>spring-restdocs-mockmvc</artifactId>
      <scope>test</scope>
    </dependency>
    <!--springfox-staticdocs 生成静态文档 -->
    <dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-staticdocs</artifactId>
      <version>2.6.1</version>
    </dependency>

<build>
    <pluginManagement>
      <plugins>
        <plugin>
          <groupId>org.springframework.boot</groupId>
          <artifactId>spring-boot-maven-plugin</artifactId>
        </plugin>
        <plugin>
          <groupId>io.github.swagger2markup</groupId>
          <artifactId>swagger2markup-maven-plugin</artifactId>
          <version>1.3.1</version>
          <configuration>
            <swaggerInput>http://127.0.0.1:8080/v2/api-docs</swaggerInput>
            <outputDir>./docs/asciidoc/generated</outputDir>
            <config>
              <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
            </config>
          </configuration>
        </plugin>
        <plugin>
          <groupId>org.asciidoctor</groupId>
          <artifactId>asciidoctor-maven-plugin</artifactId>
          <version>1.5.3</version>
          <!-- <version>2.0.0-RC.1</version> -->
          <!-- Include Asciidoctor PDF for pdf generation -->
          <dependencies>
            <dependency>
              <groupId>org.asciidoctor</groupId>
              <artifactId>asciidoctorj-pdf</artifactId>
              <version>1.5.0-alpha.10.1</version>
            </dependency>
            <dependency>
              <groupId>org.jruby</groupId>
              <artifactId>jruby-complete</artifactId>
              <version>1.7.21</version>
            </dependency>
          </dependencies>
          <configuration>
            <sourceDirectory>./docs/asciidoc/generated</sourceDirectory>
            <outputDirectory>./docs/asciidoc/html</outputDirectory> 
            <backend>html</backend>
            <!-- <outputDirectory>./docs/asciidoc/pdf</outputDirectory>
            <backend>pdf</backend> -->
            <headerFooter>true</headerFooter> 
            <doctype>book</doctype> 
            <sourceHighlighter>coderay</sourceHighlighter>
            <attributes>
              <!-- 菜单栏在左边 -->
              <toc>left</toc>
              <!-- 多标题排列 -->
              <toclevels>3</toclevels>
              <!-- 自动打数字序号 -->
              <sectnums>true</sectnums>
            </attributes>
          </configuration>          
        </plugin>
      </plugins>
    </pluginManagement>

  </build>

可以修改此处 html 和 pdf，通过 mvn asciidoctor:process-asciidoc 可以导出相应格式文件

<outputDirectory>./docs/asciidoc/html</outputDirectory> 
            <backend>html</backend>

执行 mvn asciidoctor:process-asciidoc 后再执行 mvn generate-resources，可在 targt/generated-docs 目录下生成 xml 格式文件。

完整代码

https://github.com/zwqh1992/Spring-Boot-2.X/tree/master/spring-boot-swagger2

说句题外话，springboot全家桶技术交流群可以加我微信，但是坑位有限哦，由于忙于工作，有时不能及时回复大家，请多包涵。

猜你喜欢1、Java : 对象不再使用时，为什么要赋值为 null ？2、一份不可多得的 Lombok 学习指南3、为什么说++i比i++效率高？4、ZooKeeper基本原理5、在 IntelliJ IDEA 中使用 Git，太方便了！6、Redis实战--使用Jedis实现百万数据秒级插入7、7 个显著提升编码效率的IntelliJ IDEA必备插件8、免费版的 IDEA 为啥不能使用 Tomcat ？
强烈推荐一位大佬的公众号

好文章，我在看❤️