I created API document with swagger2 and then have to make it to PDF. References are like these :
- http://swagger2markup.github.io/swagger2markup/1.3.1/#_maven_plugin
- https://github.com/Swagger2Markup/swagger2markup-maven-project-template
1. pom.xml
: swagger2 dependency, swagger2markup elements.
<properties>
<!-- Swagger2markup -->
<swagger2markup.version>1.3.1</swagger2markup.version>
<swagger2markup.plugin.version>1.3.1</swagger2markup.plugin.version>
<asciidoctorj.version>1.5.4</asciidoctorj.version>
<jruby.version>1.7.24</jruby.version>
<swagger.input>http://localhost:8080/v2/api-docs.json</swagger.input>
<asciidoctor.html.output.directory>${project.build.directory}/asciidoc/html</asciidoctor.html.output.directory>
<asciidoctor.pdf.output.directory>${project.build.directory}/asciidoc/pdf</asciidoctor.pdf.output.directory>
<asciidoctor.input.directory>${project.basedir}/src/docs</asciidoctor.input.directory>
<generated.asciidoc.directory>${project.build.directory}/asciidoc</generated.asciidoc.directory>
</properties>
<!-- Swagger2markup -->
<pluginRepositories>
<pluginRepository>
<id>jcenter-snapshots</id>
<name>jcenter</name>
<url>http://oss.jfrog.org/artifactory/oss-snapshot-local/</url>
</pluginRepository>
<pluginRepository>
<snapshots>
<enabled>false</enabled>
</snapshots>
<id>jcenter-releases</id>
<name>jcenter</name>
<url>http://jcenter.bintray.com</url>
</pluginRepository>
</pluginRepositories>
<dependencies>
<!-- Swagger2 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.6.1</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.6.1</version>
</dependency>
</dependencies>
<build>
<pluginManagement>
<plugins>
<!-- Swagger2markup -->
<!-- First, use the swagger2markup plugin to generate asciidoc -->
<plugin>
<groupId>io.github.swagger2markup</groupId>
<artifactId>swagger2markup-maven-plugin</artifactId>
<version>${swagger2markup.plugin.version}</version>
<dependencies>
<dependency>
<groupId>io.github.swagger2markup</groupId>
<artifactId>swagger2markup</artifactId>
<version>${swagger2markup.version}</version>
</dependency>
</dependencies>
<configuration>
<swaggerInput>${swagger.input}</swaggerInput>
<outputDir>${generated.asciidoc.directory}</outputDir>
<config>
<swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
<swagger2markup.pathsGroupedBy>TAGS</swagger2markup.pathsGroupedBy>
</config>
</configuration>
<executions>
<execution>
<phase>generate-sources</phase>
<goals>
<goal>convertSwagger2markup</goal>
</goals>
</execution>
</executions>
</plugin>
<!-- Run the generated asciidoc through Asciidoctor to generate other
documentation types, such as PDFs or HTML5 -->
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>1.5.3</version>
<!-- Include Asciidoctor PDF for pdf generation -->
<dependencies>
<dependency>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctorj-pdf</artifactId>
<version>1.5.0-alpha.10.1</version>
</dependency>
<!-- Comment this section to use the default jruby artifact provided
by the plugin -->
<dependency>
<groupId>org.jruby</groupId>
<artifactId>jruby-complete</artifactId>
<version>${jruby.version}</version>
</dependency>
<!-- Comment this section to use the default AsciidoctorJ artifact
provided by the plugin -->
<dependency>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctorj</artifactId>
<version>${asciidoctorj.version}</version>
</dependency>
</dependencies>
<!-- Configure generic document generation settings -->
<configuration>
<sourceDirectory>src/doc/asciidoc</sourceDirectory>
<sourceDocumentName>index.adoc</sourceDocumentName>
<backend>html5</backend>
<attributes>
<doctype>book</doctype>
<toc>left</toc>
<toclevels>3</toclevels>
<numbered></numbered>
<hardbreaks></hardbreaks>
<sectlinks></sectlinks>
<sectanchors></sectanchors>
<generated>${generated.asciidoc.directory}</generated>
</attributes>
</configuration>
<!-- Since each execution can only handle one backend, run separate
executions for each desired output type -->
<executions>
<execution>
<id>output-html</id>
<phase>generate-resources</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<backend>html5</backend>
<outputDirectory>${asciidoctor.html.output.directory}</outputDirectory>
</configuration>
</execution>
<execution>
<id>output-pdf</id>
<phase>generate-resources</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<backend>pdf</backend>
<outputDirectory>${asciidoctor.pdf.output.directory}</outputDirectory>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</pluginManagement>
</build>
2. index.adoc
: 이 파일을 src/doc/asciidoc 경로로 하여 생성해준다. 일종의 welcome file이다.
create this file on src/doc/asciidoc, a kind of welcome file (start point). content is like this :
1
2
3
4
|
include::{generated}/overview.adoc[]
include::{generated}/paths.adoc[]
include::{generated}/definitions.adoc[]
include::{generated}/security.adoc[]
| cs |
- 순서는 swagger.json => asciidoc => html or pdf 이렇게 변환한다.
- swagger.input : 생성된 swagger.json 문서 기본경로. swagger는 config를 만들어서 본인 웹앱에 연결해주면 바로 생성된다. swagger-ui.html이 아니라 json파일로 접근해야 한다. 혹은 프로젝트 디렉토리에 놨다면 그 경로를 지정한다.
Swagger.json(api-docs.json) is created as creating swagger config file and connecting to your webapp. you have to set up path of api-docs, not swagger-ui.html. O if you have you own json or yaml file, connect that physical path.
- maven으로 빌드한다면, CLI에 다음과 같이 빌드한다. json파일을 asciidoc으로 변환하는 작업이다. 이때 html로는 자동으로 generate 한다. 이를 성공하면 해당 프로젝트 디렉토리의 target에 asciidoc 폴더가 생성될 것이다.
if you build project with maven, do it like this. at the moment maven will generate html automatically if you descript elements on pom.xml. when success, you can see the asciidoc folder in your project directory.
1
|
mvn clean swagger2markup:convertSwagger2markup asciidoctor:process-asciidoc
| cs |
- pdf로 변환할 때는 다음과 같이 옵션을 붙여주어 빌드한다. wanna pdf, build with option.
1
|
mvn clean swagger2markup:convertSwagger2markup asciidoctor:process-asciidoc@output-pdf
| cs |
댓글 없음:
댓글 쓰기