码迷,mamicode.com
首页 > 其他好文 > 详细

swagger的daochu

时间:2019-12-19 13:02:55      阅读:100      评论:0      收藏:0      [点我收藏+]

标签:show   sep   存在   配置   ade   导出   spl   int   nal   

  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两种格式,目录分别为

target\docs\asciidoc\html\index.html
target\docs\asciidoc\pdf\index.pdf

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

 

注意:

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

swagger的daochu

标签:show   sep   存在   配置   ade   导出   spl   int   nal   

原文地址:https://www.cnblogs.com/wq-9/p/12066910.html

(0)
(0)
   
举报
评论 一句话评论(0
登录后才能评论!
© 2014 mamicode.com 版权所有  联系我们:gaon5@hotmail.com
迷上了代码!