今天学习了使用Swagger2生成RestAPI接口文档的技能。我这里生成的是html格式的,使用流程及其遇到的问题,做个解说和记录。我这里使用的方式是,单独搭建swagger2的本地项目生成的。
生成RestAPI接口文档的步骤
-
Step 1:
在本地搭建Swagger2doc的项目(该项目的来源,尚待考证); -
启动自己的微服务,访问路径(http://localhost:8081/v2/api-docs),得到密密麻麻的json字符串;
将上面生成json字符串放在Swagger官网的Editor官网地址
页面会生成具有json格式的json文档,拷贝到 swagger官网的在线编辑,去掉不需要的接口或者内容。 -
将最终修改好的JSON文件保存生json格式的文件,下载下来swagger.json。
-
上一步中生成的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文档的方式有好多种,后面可以继续学习。这里只是做个记录。