Swagger2生成RestAPI接口文档（html）

今天学习了使用Swagger2生成RestAPI接口文档的技能。我这里生成的是html格式的，使用流程及其遇到的问题，做个解说和记录。我这里使用的方式是，单独搭建swagger2的本地项目生成的。

生成RestAPI接口文档的步骤

1. Step 1：
   在本地搭建Swagger2doc的项目（该项目的来源，尚待考证）；

2. 启动自己的微服务，访问路径(http://localhost:8081/v2/api-docs)，得到密密麻麻的json字符串;
   将上面生成json字符串放在Swagger官网的Editor官网地址
   页面会生成具有json格式的json文档，拷贝到 swagger官网的在线编辑，去掉不需要的接口或者内容。

3. 将最终修改好的JSON文件保存生json格式的文件，下载下来swagger.json。

4. 上一步中生成的swagger.json文件放到我们第一步中搭建的本地swagger项目，替换原来的swagger.json文件。重新编译项目，就会在build中生成index.html文件，这就是我们需要的API文档

在生成API中遇到了一个问题，就是有一个REST API 的返回值类型是ResultDTO，这个DTO中有两个属性stautsCode和profile，在生成的文档中，这个DTO的属性也就有两个，这两个属性的名字是根据什么命名的呢，是根据statusCode和profile这两个属性命名格式和他们的getXXX和setXXX方法。Swagger2很有可能只去解析setXXX方法的XXX来命名，所以最好是修改或定义好属性名称之后，重新自动生成get和set方法，从而是的Swagger2能够在文档中将属性解析成你想要的样子。

import com.ddm.exception.Status;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import java.io.Serializable;

/**
 * AMUserProfileDto, login result.
 */
@ApiModel
public class ResultDTO implements Serializable {

    @ApiModelProperty(example = "10053", notes = "result status")
    private String status;
    @ApiModelProperty(notes = "information")
    private fileDTO profile;
    public String getStatus() {
        return statusCode;
    }
    public void setStatus(String status) {
        this.status = status;
    }
    public UserProfile getProfile() {
        return profile;
    }
    public void setProfile(ProfileDTO profile) {
        this.profile = profile;
    }
}

##其他需要注意的问题：
Swagger2中API文档中若出现#等特殊字符；应为这里最终生成的是html5文档，特殊字符需要转义#使用[& # 3 5;]替换(中间没有空格)。

Swagger2生成API文档的方式有好多种，后面可以继续学习。这里只是做个记录。