开源API⽂档⼯具-swagger2与smart-doc⽐较与使⽤
⼯具开源地址
swagger2 :
smart-doc： 国产
两者的⽐较
swagger2 和 smart-doc 两个开源⼯具 都可以 使⽤jar包 ⽣成 api ⽂档。
相同点：
这个两个⼯具 都可以 ⾃动 扫描 有 @Controller 注解的 类 并⽣成 相应的 api 接⼝⽂档。都可以⽣成 静态⽹页，提供在线api html 页⾯的访问。
区别：
1、swagger2相对 功能多⼀点，它不仅能 ⽣成 ⽂档 ，⽽且还可以 提供在线测试 api 的页⾯，⽅便调试。尤其是post 请求调试，不需要⾃⼰写 json 格式请求数据了，只要在对应的请求属性输⼊对应的值就可以
测试了，这个功能⽐较⽅便。⽽ smart-doc 只能⽣成 ⽂档，格式包含（多种格式⽂档：Markdown、HTML5、Asciidoctor、Postman json）
2、设计思路不同，smart-doc 是基于 源码分析的，它⽣成api⽂档是通过分析JAVA源码主要是通过 注释 和 系统⾃带注解，来实现⽂档的 ⽣成，⽽ swagger 是运⾏时 ⾃动⽣成在线⽂档，并且 ⽣成 测试 接⼝的 案例。由于他们设计思路 理念 不⼀样，swagger2 使⽤过程需要使⽤它定义的@API 相关注解，这样就污染了源码，代码⼊侵有点⾼，⽽smart -doc 就不⼀样了，主要是通过 注释 、解析/** */ 来⽣成API⽂档的 。这样基本上没有⼊侵性，很⾃由！
3、swagger ⽣成 离线的⽂档 需要借助第三⽅jar包实现，⽽ smart-doc 直接 运⾏ test ⽅法就可以直接导出 md，html，asciidoc 等格式⽂档。
两个⼯具的使⽤
（基于 spring-boot的 使⽤Demo） 使⽤maven 构建项⽬和管理依赖的
swagger2:
1、引⼊依赖包
<springfox-swagger2.version>2.9.2</springfox-swagger2.version>
<!-- swagager api 依赖包 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>${springfox-swagger2.version}</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>${springfox-swagger2.version}</version>
</dependency>
2、编写swagger 配置类
@Configuration
@EnableSwagger2
public class Swagger2Config extends WebMvcConfigurationSupport {
public static final String SWAGGER_SCAN_BASE_PACKAGE = "org.demo.SpringCloud.web";
public static final String VERSION = "1.0.0";
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.
apis(RequestHandlerSelectors.basePackage(SWAGGER_SCAN_BASE_PACKAGE))//api接⼝包扫描路径
.paths(PathSelectors.any())//可以根据url路径设置哪些请求加⼊⽂档，忽略哪些请求
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Swagger2 接⼝⽂档⽰例")//设置⽂档的标题
.description("更多内容请关注：www.baidu")//设置⽂档的描述->1.Overview
.version(VERSION)//设置⽂档的版本信息-> 1.1 Version information
.contact(new Contact("SpringCloud", "www.baidu", "geekswg@qq"))//设置⽂档的联系⽅式->1.2 Contact information .termsOfServiceUrl("baidu")//设置⽂档的License信息-
>1.3 License information
.build();
}
/**
* 防⽌@EnableMvc把默认的静态资源路径覆盖了，⼿动设置的⽅式
* @param registry
*/
@Override
protected void addResourceHandlers(ResourceHandlerRegistry registry) {
// 解决静态资源⽆法访问
registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
/
/ 解决swagger⽆法访问
registry.addResourceHandler("/swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
// 解决swagger的js⽂件⽆法访问
registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
}
}
3、启动项⽬访问 swagger-ui
smart-doc
1、引⼊依赖包
<smart-doc.version>1.8.6</smart-doc.version>
<!-- smart-doc 依赖包 -->
<dependency>
<groupId>com.github.shalousun</groupId> <artifactId>smart-doc</artifactId>
<version>${smart-doc.version}</version> <scope>test</scope>
</dependency>
2、使⽤ @Test ⽅法⽣成 api ⽂档
@Test
public void testBuilderControllersApi() {
ApiConfig config = new ApiConfig();
//当把AllInOne设置为true时，Smart-doc将会把所有接⼝⽣成到⼀个Markdown、HHTML或者AsciiDoc中
config.setAllInOne(true);
config.setLanguage(DocLanguage.CHINESE);
//Set the api document output path.
config.setOutPath("d:/smart-doc/");
//⽣成Markdown⽂件
ApiDocBuilder.buildApiDoc(config);
}
@Test
public void testBuilderControllersApiHtml() {
String OUTPUT_PATH = "smart-doc/html/";
ApiConfig config = new ApiConfig();
config.setServerUrl("127.0.0.1:8080");
//设置为严格模式，Smart-doc将降⾄要求每个Controller暴露的接⼝写上标准⽂档注释
// config.setStrict(true);
//当把AllInOne设置为true时，Smart-doc将会把所有接⼝⽣成到⼀个Markdown、HHTML或者AsciiDoc中
config.setAllInOne(true);
config.setLanguage(DocLanguage.CHINESE);
//HTML5⽂档，建议直接放到src/main/resources/static/doc下，Smart-doc提供⼀个配置常量HTML_DOC_OUT_PATH
config.setOutPath(DocGlobalConstants.HTML_DOC_OUT_PATH);
config.setOutPath(OUTPUT_PATH);
// 设置接⼝包扫描路径过滤，如果不配置则Smart-doc默认扫描所有的接⼝类
// 配置多个报名有英⽂逗号隔开
// config.setPackageFilters("com.ller");
//设置公共请求头.如果不需要请求头，则⽆需设置
// config.setRequestHeaders(
// ApiReqHeader.header().setName("access_token").setType("string")
// .setDesc("Basic auth credentials").setRequired(true).setSince("v1.1.0"),
// ApiReqHeader.header().setName("user_uuid").setType("string").setDesc("User Uuid key")
// );
//设置错误错列表，遍历⾃⼰的错误码设置给Smart-doc即可
List<ApiErrorCode> errorCodeList = new ArrayList<>();
for (HttpCodeEnum codeEnum : HttpCodeEnum.values()) {
ApiErrorCode errorCode = new ApiErrorCode();
errorCode.Code()).Message());
errorCodeList.add(errorCode);
}
//不需要显⽰错误码，则可以不⽤设置错误码。
config.setErrorCodes(errorCodeList);
//1.7.9 优化了错误码处理，⽤于下⾯替代遍历枚举设置错误码
//不需在⽂档中展⽰错误码则可以不设置。
// config.setErrorCodeDictionaries(
/
/ ApiErrorCodeDictionary.dict().setEnumClass(HttpCodeEnum.class)
// .setCodeField("code") //错误码值字段名
// .setDescField("desc")//错误码描述
// );
//设置⽂档变更记录，没有需要可以不设置
// config.setRevisionLogs(
// Log().setRevisionTime("2018/12/15").setAuthor("chen").setRemarks("test").setStatus("create").setVersion("V1.0"), // Log().setRevisionTime("2018/12/16").setAuthor("chen2").setRemarks("test2").setStatus("update").setVersion("V2.0") // );
long start = System.currentTimeMillis();
//since 1.8.1版本开始⼊⼝⽅法有变更
HtmlApiDocBuilder.buildApiDoc(config);
long end = System.currentTimeMillis();
DateTimeUtil.printRunTime(end, start);
}
⽣成⽂档⽂件
总结：enum怎么用
如果 你 只想 ⽣成 api ⽂档功能的 话 推荐使⽤ smart - doc ，更⽅便 ⽆⼊侵！ 如果你不仅想⽣成⽂档，还想使⽤ 测试接⼝ 功能，那就⽤swagger 吧！
版权声明：本站内容均来自互联网，仅供演示用，请勿用于商业和其他非法用途。如果侵犯了您的权益请与我们联系QQ:729038198，我们将在24小时内删除。
发表评论