背景

• 服务端开发同学需要花很多时间编写和维护大量的Rest接口文档，且往往接口修改后没有及时同步文档，让对接方和后续维护者一头雾水。
• 有没有一种方式可以相对容易地生成可读性好的Rest文档，并且做到与代码同步？

目标

• 通过Swagger注释自动生成Rest文档接口。
• 通过Swagger2Markup生成静态文档（html/markdown/wiki）

使用Swagger注解自动生成Rest文档接口

maven引入Swagger依赖

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

配置Swagger

@SpringBootApplication
@EnableSwagger2
public class AppStarter extends WebMvcConfigurerAdapter {public static void main(String[] args) {
        SpringApplication.run(AppStarter.class, args);
    }
    /**
     * 创建Rest Api描述
     * @return
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()                       //按条件指定生成文档接口
                .paths(PathSelectors.any())
                .build();
    }
	 /**
     * 接口描述
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("测试项目")
                .description("User实体CRUD")
                .version("1.0")
                .build();
    }
}

• EnableSwagger2启动Swagger
• 创建Docket

使用Swagger注解

controller注解

@RestController
@RequestMapping("/v1/users")
@Api(description = "用户管理接口")
public class UserController {
    @PostMapping
    @ApiOperation("创建用户")
    public void addUser(@RequestBody User user){
    }
    @GetMapping
    @ApiOperation("查询用户")
    public List<User> getUsers(@ApiParam(value = "模糊查询用户名") String name){
        return Lists.newArrayList(
                User.builder().id(1).name("test-name1").birth(new Date()).build(),
                User.builder().id(2).name("test-name2").birth(new Date()).build()
        );
    }
    @GetMapping("/{id}")
    @ApiOperation("获取用户")
    public User getUser(@ApiParam(value = "用户ID") @PathVariable long id){
        return User.builder().id(id).name("test-name").birth(new Date()).build();
    }
    @PutMapping("/{id}")
    @ApiOperation("修改用户")
    public void updateUser(@ApiParam(value = "用户ID") @PathVariable long id,
                           @RequestBody User user){
    }
    @DeleteMapping("/{id}")
    @ApiOperation("删除用户")
    public void deleteUser(@ApiParam(value = "用户ID") @PathVariable long id){
    }
}

注解	作用域	说明
Api	controller类名	描述controller
ApiOperate	controller方法	描述接口方法
ApiParam	path或param参数	描述接口参数

实体注解

@ApiModel("用户")
public class User {
    @ApiModelProperty("用户ID")
    private long id;
    @ApiModelProperty("用户名")
    private String name;
    @ApiModelProperty("生日")
    private Date birth;
}

注解	作用域	说明
ApiModel	实体类名	描述实体
ApiModelProperty	实体属性	描述属性

生成api-docs

• 打好注解后，编译，启动项目。
• swagger会在springmvc中创建 GET http://host:port/v2/api-docs 接口，输出json格式的rest api文档

使用Swagger2Markup生成静态文档

• 有了swagger的文档api，需要将其生成可读的文本文档（html/markdown/wiki），并静态化。

启动项目

• 将写好注解的项目启动，并保证/v2/api-docs接口可以访问。

配置swagger2markup插件

• maven.build.plugins增加swagger2markup插件

<plugin>
    <groupId>io.github.swagger2markup</groupId>
    <artifactId>swagger2markup-maven-plugin</artifactId>
    <version>1.3.1</version>
    <configuration>
        <!-- api-docs访问url -->
        <swaggerInput>http://localhost:8080/v2/api-docs</swaggerInput>
        <!-- 生成为单个文档，输出路径 -->
        <outputFile>src/docs/asciidoc/generated/all</outputFile>
        <!-- 生成为多个文档，输出路径 -->
        <!--<outputDir>src/docs/asciidoc/generated</outputDir>-->
        <config>
            <!-- wiki格式文档 -->
            <swagger2markup.markupLanguage>CONFLUENCE_MARKUP</swagger2markup.markupLanguage>
            <!-- ascii格式文档 -->
            <!--<swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>-->
            <!-- markdown格式文档 -->
            <!--<swagger2markup.markupLanguage>MARKDOWN</swagger2markup.markupLanguage>-->
            <swagger2markup.pathsGroupedBy>TAGS</swagger2markup.pathsGroupedBy>
        </config>
    </configuration>
</plugin>

运行swagger2markup插件

• mvn命令运行swagger2markup:convertSwagger2markup
• 在项目的/src/docs/asciidoc/generated中找到结果文件

处理结果文件

CONFLUENCE_MARKUP（wiki）

• confluence的wiki支持此格式

• 使用插入”wiki标记“

  
  

• 选择“企业维基”，将内容复制进去

  
  

• MARKDOWN

  • 可用在任何支持markdown的编辑器中

  ASCIIDOC（html）

  • ascii文档，可以再进一步将其转换为可读性优秀的html文档

  配置asciidoctor插件

  • maven.build.plugins中增加配置

  <plugin>
      <groupId>org.asciidoctor</groupId>
      <artifactId>asciidoctor-maven-plugin</artifactId>
      <version>1.5.6</version>
      <configuration>
          <!-- asciidoc文档输入路径 -->
          <sourceDirectory>src/docs/asciidoc/generated</sourceDirectory>
          <!-- html文档输出路径 -->
          <outputDirectory>src/docs/asciidoc/html</outputDirectory>
          <backend>html</backend>
          <sourceHighlighter>coderay</sourceHighlighter>
          <!-- html文档格式参数 -->
          <attributes>
              <doctype>book</doctype>
              <toc>left</toc>
              <toclevels>3</toclevels>
              <numbered></numbered>
              <hardbreaks></hardbreaks>
              <sectlinks></sectlinks>
              <sectanchors></sectanchors>
          </attributes>
      </configuration>
  </plugin>
  

  运行asciidoctor插件

  参考资料

  • swagger-api
  • swagger2markup
  • http://blog.didispace/springbootswagger2/
  • http://blog.didispace/swagger2markup-asciidoc/

  原文：https://www.jianshu/p/0438034ee55f