背景
通常我们在服务提供交互时，经常会被要求提供api文档，各种情况和格式要求都会有，如pdf，showdoc，word以及html等。其中做甲方项目的苦力面对最多的就是我们今天的目的格式word。swagger2有很多现成的可以支持的（可不可用需要自己测试），但是我为了偷懒文档生成，直接使用了最新的swagger3，接下来就是我不断折腾找工具，改工具的过程记录和最后的缝合怪。
折腾
经过搜索后找到一个不能用的swagger2word，而且只支持swagger2。看了几眼，改造成本过大，放弃。
然后找到官方维护的swagger-parser，这个倒是支持swagger3，但是这个有一个问题就是需要自己去写模版来套对象做输出（心累，收藏夹里吃灰吧）。
那么最后瞄准一个已经遗弃的项目swagger2markup，作者没有太多的精力去维护，但是本身功能完善，文档详尽，但是！它不支持swagger3。而且它支持的格式为ASCIIDOC,MARKDOWN。但是我有神器Typora啊（这篇文章也是用这个编辑器写的）。支持导出为pdf、html、word。所以决定用它了。
本想通过引入新版本的swagger-parser，让其直接支持swagger3的openapi spec 不，我不想，太累人了。
最后思路变为：
swagger3生成json->想办法将其转化为swagger2->使用swagger2markup生成markdown->Typora将markdown转化为word->完美Over
成功流程
生成swagger3的json文件
1
2
3
4
5
| cd targetProject
mvnd8 clean package -DskipTests -Pdev
mvnd8 spring-boot:run
wget http://localhost:8080/v3/api-docs
mv api-docs api.json
|
转换
安装工具
1
| npm install -g api-spec-converter
|
执行转换
1
| api-spec-converter --from=openapi_3 --to=swagger_2 api.json > swagger2.json
|
导出markdown
新建一个maven工程，加入配置
1
2
3
4
5
6
7
8
9
10
11
12
13
| <dependencies>
<dependency>
<groupId>io.github.swagger2markup</groupId>
<artifactId>swagger2markup</artifactId>
<version>1.3.4</version>
</dependency>
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-models</artifactId>
<version>1.5.24</version>
</dependency>
</dependencies>
|
编写一个main方法
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
| import io.github.swagger2markup.Language;
import io.github.swagger2markup.MarkupLanguage;
import io.github.swagger2markup.Swagger2MarkupConfig;
import io.github.swagger2markup.Swagger2MarkupConverter;
import io.github.swagger2markup.builder.Swagger2MarkupConfigBuilder;
import java.nio.file.Path;
import java.nio.file.Paths;
public class MyTest {
public static void main(String[] args) {
Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
.withSeparatedDefinitions()
.withMarkupLanguage(MarkupLanguage.MARKDOWN)
.withOutputLanguage(Language.ZH)
.build();
Path localSwaggerFile = Paths.get("~/Downloads/test/swagger2.json");
Path outputDirectory = Paths.get("~/Downloads/test");
Swagger2MarkupConverter converter = Swagger2MarkupConverter.from(localSwaggerFile)
.withConfig(config)
.build();
converter.toFolder(outputDirectory);
}
}
|
注意：这里生成markdown是分离的，需要手动整合在一起，本来应该可以配置生成一个文件，但是我没找到配置。
合成一个markdown文件后，使用typora打开，就可以导出为目标文件格式了。
knife4j方式
没什么好说的，支持openapi，内置springfox，可以完美兼容。
使用以下依赖
1
2
3
4
5
6
7
8
9
10
11
12
|
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>3.0.3</version>
</dependency>
|
添加knife4j配置
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
| import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
@Configuration
@EnableOpenApi
@EnableKnife4j
public class Knife4jConfiguration {
@Bean
public Docket docket() {
return new Docket(DocumentationType.OAS_30).apiInfo(
new ApiInfoBuilder()
.contact(new Contact("chaos", "", ""))
.title("swagger")
.version("v1.0.0")
.description("api system")
.build()
).select()
.apis(RequestHandlerSelectors.basePackage("org.example.demo"))
.paths(PathSelectors.any())
.build();
}
}
|
注意：这里有一个springfox与springboot的冲突性bug，需要添加spring.mvc.pathmatch.matching-strategy=ant_path_matcher到application.properties。
参考
api-spec-converter
swagger2markup
knife4j