Overview
Swagger and OpenAPI Specification is a great way to describe RESTful interfaces. We write OpenAPI definitions in YAML or JSON. Sometimes you may need to export OpenAPI definitions into html or word document. In the post, we are going to discuss how to export swagger specification as html or word document.
Convert OpenAPI definitions into html document
We use swagger2markup-maven-plugin to convert OpenAPI definitions from YAML or JSON to ASCIIDOC format.
Then we use asciidoctor-maven-plugin to convert ASCIIDOC into html document.
Simply add swagger2markup-maven-plugin and asciidoctor-maven-plugin to the pom.xml file:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
<project ...>
...
<build>
<plugins>
<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-import-files-ext</artifactId>
<version>${swagger2markup.extension.version}</version>
</dependency>
<dependency>
<groupId>io.github.swagger2markup</groupId>
<artifactId>swagger2markup</artifactId>
<version>${swagger2markup.version}</version>
</dependency>
</dependencies>
<configuration>
<swaggerInput>${SWAGGER_INPUT_FILE_PATH}</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>
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>${asciidoctor.maven.plugin.version}</version>
<configuration>
<sourceDirectory>${ASCIIDOC_INPUT_FOLDER_PATH}</sourceDirectory>
<sourceDocumentName>${ASCIIDOC_INPUT_FILE_NAME}</sourceDocumentName>
<attributes>
<doctype>book</doctype>
<toc>left</toc>
<toclevels>3</toclevels>
<numbered></numbered>
<hardbreaks></hardbreaks>
<sectlinks></sectlinks>
<sectanchors></sectanchors>
<generated>${ASCIIDOC_OUTPUT_FOLDER_PATH}</generated>
</attributes>
</configuration>
<executions>
<execution>
<id>output-html</id>
<phase>generate-resources</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<backend>html5</backend>
<outputDirectory>${HTML_OUTPUT_FOLDER_PATH}</outputDirectory>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
</project>
Convert html into docx document
Then we use pandoc to convert html to docx document.
Simply use the following command:
1
pandoc.exe --from html --to docx -o definitions.docx index.html
Pandoc is a swiss-army knife so you can convert to and from different file formats.
You could find out more with the following command:
1
pandoc.exe -h
Conclusion
We have described how to export swagger specification as html or word document.
Links:
https://github.com/Swagger2Markup/swagger2markup-maven-project-template
