[Spring] Springfox-swagger 적용하여 API문서 자동 생성 하기(asciidoc, markdown)

• pom.xml 에 dependency 및 plugin 추가

<dependency>             <groupId>io.springfox</groupId>             <artifactId>springfox-swagger2</artifactId>             <version>2.3.0</version>             <scope>test</scope>         </dependency>         <dependency>             <groupId>io.springfox</groupId>             <artifactId>springfox-staticdocs</artifactId>             <version>2.3.0</version>             <scope>test</scope>         </dependency>         <dependency>             <groupId>io.github.robwin</groupId>             <artifactId>swagger2markup</artifactId>             <version>0.9.1</version>             <scope>test</scope>         </dependency>         <plugins>             <plugin>                 <groupId>org.asciidoctor</groupId>                 <artifactId>asciidoctor-maven-plugin</artifactId>                 <version>1.5.2</version>                 <executions>                     <execution>                         <id>generate-docs</id>                         <phase>package</phase>                         <goals>                             <goal>process-asciidoc</goal>                         </goals>                         <configuration>                             <sourceDirectory>src/docs/asciidoc</sourceDirectory>                             <backend>html</backend>                             <attributes>                                 <toclevels>2</toclevels>                                 <toc>left</toc>                                 <doctype>book</doctype>                                 <generated>src/docs/asciidoc/generated</generated>                             </attributes>                         </configuration>                     </execution>                 </executions>             </plugin>         </plugins>

• 테스트 코드 설정

import org.springframework.context.annotation.Configuration;     import springfox.documentation.swagger2.annotations.EnableSwagger2;     @Configuration     @EnableSwagger2     public class ApiDocConfig {     }

•  문서 생성 테스트 코드

@Test     public void convertSwaggerToAsciiDoc() throws Exception{  // asciidoc 생성코드         this.mockMvc.perform(get("/v2/api-docs").accept(MediaType.APPLICATION_JSON))                 .andDo(Swagger2MarkupResultHandler.outputDirectory("src/docs/asciidoc/generated").build()).andExpect(status().isOk());     }     @Test     public void convertSwaggerToMarkdown() throws Exception{ // markdown 생성코드         this.mockMvc.perform(get("/v2/api-docs").accept(MediaType.APPLICATION_JSON))                 .andDo(Swagger2MarkupResultHandler.outputDirectory("src/docs/markdown/generated").withMarkupLanguage(MarkupLanguage.MARKDOWN).build())                 .andExpect(status().isOk());     }

• 문서 생성 후 폴더 구조
• • target 폴더에 html 형식으로 api 문서가 생성된다.  

• index.adoc 
• • definitions, overview, paths  파일의 내용을 통합하여 보여주기 위한 설정
  • include::generated/overview.adoc[]
    include::generated/definitions.adoc[]
    include::generated/paths.adoc[]
  
  
• 문서 예시