跟着JHipster学做项目(2) - 使用Swagger2生成API文档 （上）生成swagger的asciidoc文件

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!