跟着JHipster學做項目(2) - 使用Swagger2生成API文檔

JHipster的提示和技巧頁面中第一個技巧就是：

1. Create a static Swagger API documentation   

雖然篇頭已經提示我們要去看swagger2markup最新模塊，不要理會下面的內容，但是看着下面僅僅三步便可以生成API文檔還是會想先按照提示嘗試一下，於是利用maven引入springfox-staticdocs

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-staticdocs</artifactId>
    <version>${springfox.version}</version>
    <scope>test</scope>
</dependency>

然而在執行Swagger2MarkupTest後成功遇到issue 289，詳情請參見swagger2markup-issues-289

按照問題描述應該引入swagger2markup- 1.3.3來取代spring-staticdocs的依賴包swagger2markup- 0.9.2

在spring-swagger2markup-demo中，爲了升級需要在maven中添加兩個repository

    <repositories>
        <repository>
            <id>jcentral</id>
            <name>bintray</name>
            <url>http://jcenter.bintray.com</url>
            <snapshots>
                <enabled>false</enabled>
            </snapshots>
        </repository>
        <repository>
            <id>jcenter-snapshots</id>
            <name>jcenter</name>
            <url>http://oss.jfrog.org/artifactory/oss-snapshot-local/</url>
        </repository>
    </repositories>

這裏會有一點小困擾，jar包無法下載，需要修正兩個url，改爲https, 另外當通過修改pom.xml文件進行jar包下載出錯後，執行mvn install是一個比較好的辦法，通常會自動下載缺失的依賴。

對於spring-swagger2markup-demo項目執行mvn install會成功生成swagger文件，以及由asciidocs插件生成的html, pdf文檔。但是不滿足於demo中Swagger2MarkupTest只生成了swagger.json文件，我們還想像JHipster技巧中那樣直接生成swagger的asciidoc文件，一般包括四個部分，overview, paths, definations, security. 

	public void convertSwaggerToAsciiDoc() throws Exception {
		this.mockMvc.perform(get(API_URI).accept(MediaType.APPLICATION_JSON))
				.andDo(new ResultHandler() {
					@Override
					public void handle(MvcResult result) throws Exception {
						String swagger = result.getResponse()
								.getContentAsString();
						Swagger2MarkupConverter.from(swagger).build().toFolder(
								Paths.get(outputDirForFormat("asciidoc")));
					}
				}).andExpect(status().isOk());
	}

運行仍然如前面一樣報issue289，no getDefaultValue() method.

查看依賴發現demo中swagger2markup的版本是1.2.0，利用eclipse的功能右鍵點擊maven,如下圖自動根據依賴排除1.2.0版本，再引入1.3.3版本。

		<dependency>
			<groupId>io.github.swagger2markup</groupId>
			<artifactId>swagger2markup</artifactId>
			<version>1.3.3</version>
            <scope>test</scope>
		</dependency>
        <dependency>
            <groupId>io.github.swagger2markup</groupId>
            <artifactId>swagger2markup-spring-restdocs-ext</artifactId>
            <version>${swagger2markup.version}</version>
            <scope>test</scope>
            <exclusions>
            	<exclusion>
            		<groupId>io.github.swagger2markup</groupId>
            		<artifactId>swagger2markup</artifactId>
            	</exclusion>
            </exclusions>
        </dependency>

再次執行，issue289成功消失，但是出現另外一個缺失snippetBaseUri的錯誤。解決這個問題有兩種方法：

第一，直接去掉依賴swagger2markup-spring-restdocs-ext

SpringRestDocsExtension作爲PathsDocumentExtension的擴展類，也會被註冊，它沒有默認配置，所以會報錯。

第二，對converter進行配置，代碼如下：

@Test
    public void createSpringfoxSwaggerJson() throws Exception {
//        String designFirstSwaggerLocation = Swagger2MarkupTest.class.getResource("/swagger.yaml").getPath();

//        String outputDir = System.getProperty("io.springfox.staticdocs.outputDir");
    	String outputDir = outputDirForFormat("asciidoc");
        config.put("swagger2markup.markupLanguage", "ASCIIDOC");
        config.put("swagger2markup.pathsGroupedBy", "TAGS");
        config.put("swagger2markup.extensions.dynamicOverview.contentPath", outputWaggerDirForFormat("src/docs/asciidoc/extensions/overview"));
        config.put("swagger2markup.extensions.dynamicDefinitions.contentPath", outputWaggerDirForFormat("src/docs/asciidoc/extensions/definitions"));
        config.put("swagger2markup.extensions.dynamicPaths.contentPath", outputWaggerDirForFormat("src/docs/asciidoc/extensions/paths"));
        config.put("swagger2markup.extensions.dynamicSecurity.contentPath", outputWaggerDirForFormat("src/docs/asciidoc/extensions/security/"));
        config.put("swagger2markup.extensions.springRestDocs.snippetBaseUri", outputWaggerDirForFormat("target/asciidoc/snippets"));
        config.put("swagger2markup.extensions.springRestDocs.defaultSnippets", "true");

        Swagger2MarkupConfig swagger2MarkupConfig = new Swagger2MarkupConfigBuilder(config).build();
        MvcResult mvcResult = this.mockMvc.perform(get("/v2/api-docs")
                .accept(MediaType.APPLICATION_JSON))
        						.andDo(new ResultHandler() {
				@Override
				public void handle(MvcResult result) throws Exception {
					String swagger = result.getResponse()
							.getContentAsString();
					Swagger2MarkupConverter.from(swagger).withConfig(swagger2MarkupConfig).build().toFolder(
							Paths.get(outputDirForFormat("asciidoc")));
				}
			}).andExpect(status().isOk()).andReturn();
        

        MockHttpServletResponse response = mvcResult.getResponse();
        String swaggerJson = response.getContentAsString();
        Files.createDirectories(Paths.get(outputDir));
        try (BufferedWriter writer = Files.newBufferedWriter(Paths.get(outputDir, "swagger.json"), StandardCharsets.UTF_8)){
            writer.write(swaggerJson);
        }
    }

Good luck,

Cheers!