生成Swagger2靜態文件
阿新 • • 發佈：2018-12-04
一、程式碼生成靜態文件
<!-- swagger生成介面API --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.6.0</version> </dependency> <!-- 介面API生成html文件 --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.6.0</version> </dependency> <dependency> <groupId>io.github.swagger2markup</groupId> <artifactId>swagger2markup</artifactId> <version>1.3.1</version> </dependency> <dependency> <groupId>io.swagger</groupId> <artifactId>swagger-core</artifactId> <version>1.5.16</version> </dependency> <dependency> <groupId>io.swagger</groupId> <artifactId>swagger-models</artifactId> <version>1.5.16</version> </dependency> <dependency> <groupId>org.pegdown</groupId> <artifactId>pegdown</artifactId> <version>1.4.2</version> </dependency>
jar包容易出問題：
正常後面兩個jar是不需要的,因為jar包容易報錯
java.lang.NoSuchMethodError: io.swagger.models.Response.responseSchema(Lio/swagger/models/Model;)Lio/swagger/models/Response;
java.lang.NoSuchFieldError: MULTIPLE_OF
因為 springfox-swagger2 --2.60這個版本里面對應的swagger-core是1.5.12 ，swagger-models是1.5.10的。想要通過swagger2markup生成靜態文件需要通過core和model轉換成對應的實體格式。然而core和model好像11前都沒有向後相容，所以需要core和model都需要在1.5.11之上。引入的 core和model就是為了替換springfox-swagger2裡面的包
Test類
import io.github.swagger2markup.GroupBy; import io.github.swagger2markup.Language; import io.github.swagger2markup.Swagger2MarkupConfig; import io.github.swagger2markup.Swagger2MarkupConverter; import io.github.swagger2markup.builder.Swagger2MarkupConfigBuilder; import io.github.swagger2markup.markup.builder.MarkupLanguage; import org.junit.Test; import org.junit.runner.RunWith; import org.springframework.boot.test.context.SpringBootTest; import org.springframework.test.context.junit4.SpringRunner; import java.net.URL; import java.nio.file.Paths; @RunWith(SpringRunner.class) @SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.DEFINED_PORT) public class UserManageApplicationTests { /** * 生成AsciiDocs格式文件 * @throws Exception */ @Test public void generateAsciiDocs() throws Exception { // 輸出Ascii格式 Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder() .withMarkupLanguage(MarkupLanguage.ASCIIDOC)//設定生成格式 .withOutputLanguage(Language.ZH)//設定語言中文還是其他語言 .withPathsGroupedBy(GroupBy.TAGS) .withGeneratedExamples() .withoutInlineSchema() .build(); //設定swagger-api的json來源 Swagger2MarkupConverter.from(new URL("http://localhost:9090/v2/api-docs")) .withConfig(config) .build() .toFolder(Paths.get("./docs/asciidoc/generated"));//設定生成檔案的路徑 } /** * 生成Markdown格式文件 * @throws Exception */ @Test public void generateMarkdownDocs() throws Exception { // 輸出Markdown格式 Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder() .withMarkupLanguage(MarkupLanguage.MARKDOWN) .withOutputLanguage(Language.ZH) .withPathsGroupedBy(GroupBy.TAGS) .withGeneratedExamples() .withoutInlineSchema() .build(); Swagger2MarkupConverter.from(new URL("http://localhost:9090/v2/api-docs")) .withConfig(config) .build() .toFolder(Paths.get("./docs/markdown/generated")); } /** * 生成Confluence格式文件 * @throws Exception */ @Test public void generateConfluenceDocs() throws Exception { // 輸出Confluence使用的格式 Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder() .withMarkupLanguage(MarkupLanguage.CONFLUENCE_MARKUP) .withOutputLanguage(Language.ZH) .withPathsGroupedBy(GroupBy.TAGS) .withGeneratedExamples() .withoutInlineSchema() .build(); Swagger2MarkupConverter.from(new URL("http://localhost:9090/v2/api-docs")) .withConfig(config) .build() .toFolder(Paths.get("./docs/confluence/generated")); } /** * 生成AsciiDocs格式文件,並彙總成一個檔案 * @throws Exception */ @Test public void generateAsciiDocsToFile() throws Exception { // 輸出Ascii到單檔案 Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder() .withMarkupLanguage(MarkupLanguage.ASCIIDOC) .withOutputLanguage(Language.ZH) .withPathsGroupedBy(GroupBy.TAGS) .withGeneratedExamples() .withoutInlineSchema() .build(); Swagger2MarkupConverter.from(new URL("http://localhost:9090/v2/api-docs")) .withConfig(config) .build() .toFile(Paths.get("./docs/asciidoc/generated/all")); } /** * 生成Markdown格式文件,並彙總成一個檔案 * @throws Exception */ @Test public void generateMarkdownDocsToFile() throws Exception { // 輸出Markdown到單檔案 Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder() .withMarkupLanguage(MarkupLanguage.MARKDOWN) .withOutputLanguage(Language.ZH) .withPathsGroupedBy(GroupBy.TAGS) .withGeneratedExamples() .withoutInlineSchema() .build(); Swagger2MarkupConverter.from(new URL("http://localhost:9090/v2/api-docs")) .withConfig(config) .build() .toFile(Paths.get("./docs/markdown/generated/all")); } }
二、通過maven外掛生成
1、生成ASCIIDOC等，效果等同上面程式碼
<plugin>
<groupId>io.github.swagger2markup</groupId>
<artifactId>swagger2markup-maven-plugin</artifactId>
<version>1.3.4</version>
<configuration>
<swaggerInput>http://localhost:9090/v2/api-docs</swaggerInput><!---swagger-api-json路徑-->
<outputDir>./docs/asciidoc/generated</outputDir><!---生成路徑-->
<config>
<swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage><!--生成格式-->
</config>
</configuration>
</plugin>
mvn執行swagger2markup:convertSwagger2markup
若遇到問題java.lang.NoClassDefFoundError: org/pegdown/PegDownProcessor修改swagger2markup-maven-plugin-1.3.4.pom增加
<dependency>
<groupId>org.pegdown</groupId>
<artifactId>pegdown</artifactId>
<version>1.4.2</version>
</dependency>
2、生成html(前提是已經存在ASCIIDOC)
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>1.5.6</version>
<configuration>
<!--asciidoc檔案目錄，請確認檔案已經存在-->
<sourceDirectory>../docs/asciidoc/generated</sourceDirectory>
<!---生成html的路徑-->
<outputDirectory>../docs/asciidoc/html</outputDirectory>
<backend>html</backend>
<sourceHighlighter>coderay</sourceHighlighter>
<attributes>
<!--導航欄在左-->
<toc>left</toc>
<!--顯示層級數-->
<toclevels>3</toclevels>
<!--自動打數字序號-->
<sectnums>true</sectnums>
</attributes>
</configuration>
</plugin>
參考： https://blog.csdn.net/qq_34727675/article/details/82961995