swagger的daochu

Posted 2021-03-22 wq-9

　　swagger-export是一个提供swagger文档导出功能的服务，不依赖于具体的API接口服务实现，你可以很方便地导出html和pdf两种格式的静态文档。源码来自swagger导出静态API文档工具，做了一些修改，以符合实际的项目需要。

 

一.在src下配置asciidoc

 

 二.pom.xml

也就是maven插件

<?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.jeesun</groupId>
    <artifactId>swagger-export</artifactId>
    <version>1.0.0</version>

    <properties>
        <swaggerInputPath>http://127.0.0.1:8080/api/v2/api-docs</swaggerInputPath>
    </properties>

    <build>
        <finalName>com-jeesun-${project.artifactId}-${project.version}</finalName>

        <plugins>
            <!--此插件生成ASCIIDOC-->
            <plugin>
                <groupId>io.github.swagger2markup</groupId>
                <artifactId>swagger2markup-maven-plugin</artifactId>
                <version>1.3.7</version>
                <dependencies>
                    <dependency>
                        <groupId>io.github.swagger2markup</groupId>
                        <artifactId>swagger2markup</artifactId>
                        <version>1.3.3</version>
                    </dependency>
                </dependencies>
                <configuration>
                    <!--此处端口一定要是当前项目启动所用的端口-->
                    <swaggerInput>${swaggerInputPath}</swaggerInput>
                    <outputDir>${project.build.directory}/docs/asciidoc/generated</outputDir>
                    <config>
                        <!-- 除了ASCIIDOC之外，还有MARKDOWN和CONFLUENCE_MARKUP可选 -->
                        <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
                        <swagger2markup.pathsGroupedBy>TAGS</swagger2markup.pathsGroupedBy>
                        <swagger2markup.outputLanguage>ZH</swagger2markup.outputLanguage>
                    </config>
                </configuration>
                <executions>
                    <execution>
                        <phase>generate-resources</phase>
                        <goals>
                            <goal>convertSwagger2markup</goal>
                        </goals>
                    </execution>
                </executions>

            </plugin>
            <!--此插件生成HTML和PDF-->
            <plugin>
                <groupId>org.asciidoctor</groupId>
                <artifactId>asciidoctor-maven-plugin</artifactId>
                <version>1.5.6</version>
                <!-- Include Asciidoctor PDF for pdf generation -->
                <dependencies>
                    <dependency>
                        <groupId>org.asciidoctor</groupId>
                        <artifactId>asciidoctorj-pdf</artifactId>
                        <version>1.5.0-alpha.16</version>
                    </dependency>
                    <!--<dependency>-->
                    <!--<groupId>org.jruby</groupId>-->
                    <!--<artifactId>jruby-complete</artifactId>-->
                    <!--<version>1.7.21</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>9.1.8.0</version>
                    </dependency>
                    <!-- Comment this section to use the default AsciidoctorJ artifact provided by the plugin -->
                    <dependency>
                        <groupId>org.asciidoctor</groupId>
                        <artifactId>asciidoctorj</artifactId>
                        <version>1.5.4</version>
                    </dependency>

                </dependencies>
                <!-- Configure generic document generation settings -->
                <configuration>
                    <sourceDirectory>src/docs/asciidoc</sourceDirectory>
                    <sourceDocumentName>index.adoc</sourceDocumentName>
                    <sourceHighlighter>coderay</sourceHighlighter>
                    <attributes>
                        <doctype>book</doctype>
                        <toc>left</toc>
                        <toclevels>3</toclevels>
                        <numbered></numbered>
                        <hardbreaks></hardbreaks>
                        <sectlinks></sectlinks>
                        <sectanchors></sectanchors>
                        <generated>${project.build.directory}/docs/asciidoc/generated</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>${project.build.directory}/docs/asciidoc/html</outputDirectory>
                        </configuration>
                    </execution>

                    <execution>
                        <id>output-pdf</id>
                        <phase>generate-resources</phase>
                        <goals>
                            <goal>process-asciidoc</goal>
                        </goals>
                        <configuration>
                            <backend>pdf</backend>
                            <outputDirectory>${project.build.directory}/docs/asciidoc/pdf</outputDirectory>
                        </configuration>
                    </execution>

                </executions>
            </plugin>
            <!-- end::plugin[] -->
        </plugins>
    </build>
    <!--<repositories>
        <repository>
            <id>jcenter-releases</id>
            <name>jcenter</name>
            <url>http://jcenter.bintray.com</url>
        </repository>
    </repositories>-->
    <pluginRepositories>
        <pluginRepository>
            <id>jcenter-releases</id>
            <name>jcenter</name>
            <url>http://jcenter.bintray.com</url>
        </pluginRepository>
    </pluginRepositories>
</project>

View Code

 

 

 

 

 

 

导出步骤

1. 启动待导出的API接口服务；

2. 修改pom文件中properties配置的swaggerInputPath值为目标服务的IP端口信息；

3. 在当前目录执行mvn clean compile命令；

4. 生成的文档有html和pdf两种格式，目录分别为

targetdocsasciidochtmlindex.html
targetdocsasciidocpdfindex.pdf

导出的pdf格式文件，中文存在显示问题。可用Word2016打开，然后另存为word格式文件。

 

注意：

导出时，如果有数据权限，得放出  /v2/api-docs 接口。