BlueXIII's Blog

热爱技术,持续学习

0%

swagger2markup生成静态API文档

Posted on

简介

swagger我们已经不陌生了，另外可以借助于swagger-ui，可以实现动态的、可测试的API文档。

本文主要介绍如何使用swagger2markup生成静态的HTML及PDF文档。

生成的文档样式如下：

swagger2markup主页

GitHub主页：
https://github.com/Swagger2Markup/swagger2markup

实现方式

swagger2markup的实现方式比较绕，pom.xml里的依赖也比较多，而且每次构建都生成文档的话，需要耗费较长的时间。
所以不建议直接集成到工程内部，可以将它独立成一个工程出来，专门用于生成文档。

配置及代码

配置及代码不多，就不上传github了，在下面直接贴出来。

实现方式大体是：

  1. 运行单元测试采集远程的swagger.json文件并保存到本地
  2. maven插件将swagger.json转换为asciidoc
  3. 将asciidoc再转为html+pdf。

用到了custom.baseurl这个JVM自定义的参数。默认情况下采集127.0.0.1:8080下的应用。
也可以在mvn后面指定-Dcustom.baseurl=xx.xx.xx.xx来实现自定义的采集，如果微服务较多，可以用start.sh脚本来进行批量采集

pom.xml

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
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>com.foo.bar</groupId>
  <artifactId>apidocs</artifactId>
  <version>1.0.0</version>
  <packaging>jar</packaging>

  <name>apidocs</name>
  <description>ApiDocs</description>

  <properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
    <java.version>1.8</java.version>

    <custom.baseurl>127.0.0.1:8080</custom.baseurl>
    <swagger2markup.version>1.3.1</swagger2markup.version>
    <asciidoctor.input.directory>${project.basedir}/src/docs/asciidoc</asciidoctor.input.directory>
    <swagger.output.dir>${project.build.directory}/swagger</swagger.output.dir>
    <swagger.snippetOutput.dir>${project.build.directory}/asciidoc/snippets</swagger.snippetOutput.dir>
    <generated.asciidoc.directory>${project.build.directory}/asciidoc/generated</generated.asciidoc.directory>
    <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>
    <swagger.input>${swagger.output.dir}/swagger.json</swagger.input>
  </properties>

  <parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>1.5.4.RELEASE</version>
  </parent>

  <dependencies>
    <!--springboot-->
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-test</artifactId>
    </dependency>
    <!--swagger2markup-->
    <dependency>
      <groupId>io.github.swagger2markup</groupId>
      <artifactId>swagger2markup-spring-restdocs-ext</artifactId>
      <version>${swagger2markup.version}</version>
      <scope>test</scope>
    </dependency>
    <dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-staticdocs</artifactId>
      <version>2.4.0</version>
    </dependency>
    <dependency>
      <groupId>io.github.robwin</groupId>
      <artifactId>assertj-swagger</artifactId>
      <version>0.2.0</version>
      <scope>test</scope>
    </dependency>
    <dependency>
      <groupId>org.springframework.restdocs</groupId>
      <artifactId>spring-restdocs-mockmvc</artifactId>
    </dependency>
  </dependencies>

  <build>
    <resources>
      <resource>
        <directory>src/main/resources</directory>
        <filtering>true</filtering>
      </resource>
    </resources>

    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-compiler-plugin</artifactId>
        <version>3.3</version>
        <configuration>
          <compilerVersion>${java.version}</compilerVersion>
          <source>${java.version}</source>
          <target>${java.version}</target>
          <encoding>UTF-8</encoding>
          <!-- prevents endPosTable exception for maven compile -->
          <useIncrementalCompilation>false</useIncrementalCompilation>
        </configuration>
      </plugin>

      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-surefire-plugin</artifactId>
        <configuration>
          <systemPropertyVariables>
            <io.springfox.staticdocs.outputDir>${swagger.output.dir}</io.springfox.staticdocs.outputDir>
            <io.springfox.staticdocs.snippetsOutputDir>${swagger.snippetOutput.dir}
            </io.springfox.staticdocs.snippetsOutputDir>
            <custom.baseurl>${custom.baseurl}</custom.baseurl>
          </systemPropertyVariables>
        </configuration>
      </plugin>

      <!-- First, use the swagger2markup plugin to generate asciidoc -->
      <plugin>
        <groupId>io.github.swagger2markup</groupId>
        <artifactId>swagger2markup-maven-plugin</artifactId>
        <version>${swagger2markup.version}</version>
        <dependencies>
          <dependency>
            <groupId>io.github.swagger2markup</groupId>
            <artifactId>swagger2markup-import-files-ext</artifactId>
            <version>${swagger2markup.version}</version>
          </dependency>
          <dependency>
            <groupId>io.github.swagger2markup</groupId>
            <artifactId>swagger2markup-spring-restdocs-ext</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>

            <swagger2markup.extensions.dynamicOverview.contentPath>
              ${project.basedir}/src/docs/asciidoc/extensions/overview
            </swagger2markup.extensions.dynamicOverview.contentPath>
            <swagger2markup.extensions.dynamicDefinitions.contentPath>
              ${project.basedir}/src/docs/asciidoc/extensions/definitions
            </swagger2markup.extensions.dynamicDefinitions.contentPath>
            <swagger2markup.extensions.dynamicPaths.contentPath>${project.basedir}/src/docs/asciidoc/extensions/paths
            </swagger2markup.extensions.dynamicPaths.contentPath>
            <swagger2markup.extensions.dynamicSecurity.contentPath>
              ${project.basedir}src/docs/asciidoc/extensions/security/
            </swagger2markup.extensions.dynamicSecurity.contentPath>

            <swagger2markup.extensions.springRestDocs.snippetBaseUri>${swagger.snippetOutput.dir}
            </swagger2markup.extensions.springRestDocs.snippetBaseUri>
            <swagger2markup.extensions.springRestDocs.defaultSnippets>true
            </swagger2markup.extensions.springRestDocs.defaultSnippets>
          </config>
        </configuration>
        <executions>
          <execution>
            <phase>test</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>
          <dependency>
            <groupId>org.jruby</groupId>
            <artifactId>jruby-complete</artifactId>
            <version>1.7.21</version>
          </dependency>
        </dependencies>
        <!-- Configure generic document generation settings -->
        <configuration>
          <sourceDirectory>${asciidoctor.input.directory}</sourceDirectory>
          <sourceDocumentName>index.adoc</sourceDocumentName>
          <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>test</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>test</phase>
            <goals>
              <goal>process-asciidoc</goal>
            </goals>
            <configuration>
              <backend>pdf</backend>
              <outputDirectory>${asciidoctor.pdf.output.directory}</outputDirectory>
            </configuration>
          </execution>

        </executions>
      </plugin>

      <!-- specify the main class for the manifest -->
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-jar-plugin</artifactId>
        <version>2.4</version>
        <configuration>
          <archive>
            <manifest>
              <addClasspath>true</addClasspath>
              <classpathPrefix>lib/</classpathPrefix>
              <mainClass>io.github.robwin.swagger2markup.petstore.Application</mainClass>
            </manifest>
          </archive>
        </configuration>
      </plugin>

      <!-- copy dependencies to the lib directory -->
      <plugin>
        <artifactId>maven-dependency-plugin</artifactId>
        <executions>
          <execution>
            <phase>package</phase>
            <goals>
              <goal>copy-dependencies</goal>
            </goals>
            <configuration>
              <outputDirectory>${project.build.directory}/lib</outputDirectory>
            </configuration>
          </execution>
        </executions>
      </plugin>

      <!-- copy the generated documents -->
      <plugin>
        <artifactId>maven-resources-plugin</artifactId>
        <version>2.7</version>
        <executions>
          <execution>
            <id>copy-resources</id>
            <phase>prepare-package</phase>
            <goals>
              <goal>copy-resources</goal>
            </goals>
            <configuration>
              <outputDirectory>${project.build.outputDirectory}/static/docs</outputDirectory>
              <resources>
                <resource>
                  <directory>${asciidoctor.html.output.directory}</directory>
                </resource>
                <resource>
                  <directory>${asciidoctor.pdf.output.directory}</directory>
                </resource>
              </resources>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
</project>

JUnit测试类

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
package com.sitech.sdtools;

import org.junit.Test;
import org.junit.runner.RunWith;
import org.springframework.boot.test.autoconfigure.restdocs.AutoConfigureRestDocs;
import org.springframework.test.context.junit4.SpringRunner;
import org.springframework.web.client.RestTemplate;

import java.io.BufferedWriter;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Paths;

@RunWith(SpringRunner.class)
@AutoConfigureRestDocs(outputDir = "build/asciidoc/snippets")
public class Swagger2MarkupTest {
    private RestTemplate restTemplate = new RestTemplate();

    @Test
    public void createSpringfoxSwaggerJson() throws Exception {
        String baseurl = System.getProperty("custom.baseurl");
        String swaggerUrl = "http://" + baseurl + "/v2/api-docs";
        String outputDir = System.getProperty("io.springfox.staticdocs.outputDir");
        System.out.println("swaggerUrl: " + swaggerUrl);
        System.out.println("outputDir: " + outputDir);

        String swaggerJson = restTemplate.getForObject(swaggerUrl, String.class);

        Files.createDirectories(Paths.get(outputDir));
        try (BufferedWriter writer = Files.newBufferedWriter(Paths.get(outputDir, "swagger.json"), StandardCharsets.UTF_8)) {
            writer.write(swaggerJson);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

批量shell脚本

start.sh 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
#!/usr/bin/env bash

# 自定义工程名及URL
prjnames=("project1" "project2" "project3")
prjurls=("xx.xx.xx.xx:7477" "xx.xx.xx.xx:23053" "xx.xx.xx.xx:24275")

# 默认参数
datestr=`date +%Y%m%d`
srcdir=./target/asciidoc/html
destdir=./src/docs/html/${datestr}
mkdir ${destdir}

# 循环生成文档
for prjname in ${prjnames[@]}
do
    prjurl=${prjurls[${i}]}
    echo "文档生成开始 - ${prjname} - ${prjurl}"

    mvn clean test -Dcustom.baseurl=${prjurl}
    cp ${srcdir}/index.html ${destdir}/${prjname}.html

    i=$((i+1))
done

单文档生成步骤

  1. 先本机将需要生成API文档的工程启动，IP及端口指定为127.0.0.1:8080
  2. 在本工程下运行mvn clean test
  3. 在target/asciidoc/html中查看API文档并拷贝出来

批量文档生成步骤

  1. 在DCOS中将所有服务启动
  2. 修改start.sh中的prjurls
  3. 执行./start.sh
  4. 在src/docs/html/日期/中查看生成的API文档