swagger2markup生成静态API文档

作者: bluexiii | 来源:发表于2017-09-16 10:33 被阅读1101次

swagger2markup生成静态API文档
[Swagger] Swagger2Markup 配置
建立iOS专属文档之Objective-C API文档生成器
SpringBoot指南|第四篇：集成swagger生成API文
apidocjs-开发人员最好用的API文档
使用Swagger2Markup实现API文档的静态部署（一）：
使用Swagger2Markup实现API文档的静态部署（一）：
生成API文档
生成api文档
api文档生成

简介

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

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

生成的文档样式如下：

swagger2markup主页

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

实现方式

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

配置及代码

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

实现方式大体是：

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

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

pom.xml

<?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测试类

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

#!/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

单文档生成步骤

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

批量文档生成步骤

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

swagger2markup生成静态API文档
简介 swagger我们已经不陌生了，另外可以借助于swagger-ui，可以实现动态的、可测试的API文档。本...
[Swagger] Swagger2Markup 配置
Swagger2Markup 配置网上很多关于Swagger静态文档的生成大多缺少关于Swagger2Marku...
建立iOS专属文档之Objective-C API文档生成器
appledoc Objective-C API文档生成器参考文 iOS使用appledoc 生成技术API文档...
SpringBoot指南|第四篇：集成swagger生成API文
SpringBoot指南|第四篇：集成swagger生成API文档本文介绍如何使用swagger生成API文档。...
apidocjs-开发人员最好用的API文档
1.特点： apidoc是根据你源代码中的API注释生成的文档，一行命令即可生成api接口文档此api文档集成...
使用Swagger2Markup实现API文档的静态部署（一）：
在阅读本文之前，您先需要了解Swagger的使用，如果您还不知道它是用来干嘛的，请先阅读《Spring Boot中...
使用Swagger2Markup实现API文档的静态部署（一）：
在阅读本文之前，您先需要了解Swagger的使用，如果您还不知道它是用来干嘛的，请先阅读《Spring Boot中...
生成API文档
Django Rest Framework - 实例PartyDemo 之 API文档 www.jianshu.c...
生成api文档
进入action.api文件夹输入命令 apidoc -i . -o d:/ksjapi
api文档生成
网上有很多教程，不难，我肯定没有他们懂，所做的不过是把繁琐的说明说简单，简要话。先下个工具http://url....