com.github.mkgoingup:docmerge-maven-plugin

Sonatype helps open source projects to set up Maven repositories on https://oss.sonatype.org/

License	The Apache Software License, Version 2.0
Categories	Maven Build Tools
GroupId	com.github.mkgoingup
ArtifactId	docmerge-maven-plugin
Last Version	1.0.2
Release Date	Sep 9, 2019
Type	maven-plugin
Description	Sonatype helps open source projects to set up Maven repositories on https://oss.sonatype.org/
Source Code Management	https://github.com/mkgoingup/spring-rest-docs-plugin/tree/master

Download docmerge-maven-plugin

Filename	Size
docmerge-maven-plugin-1.0.2.pom
docmerge-maven-plugin-1.0.2.jar	10 KB

How to add to project

Apache Maven

<plugin>
    <groupId>com.github.mkgoingup</groupId>
    <artifactId>docmerge-maven-plugin</artifactId>
    <version>1.0.2</version>
</plugin>

Dependencies

compile (2)

Group / Artifact	Type	Version
org.apache.maven : maven-plugin-api	jar	3.5.0
org.apache.maven.plugin-tools : maven-plugin-annotations	jar	3.5

Project Modules

There are no modules declared in this project.

spring-rest-docs-plugin

功能

spring rest docs 的maven 插件,自动合并碎片文档

结合asciidoctor-maven-plugin插件自动生成api的HTML文档，合并的碎片文档包括:

curl-request.adoc
http-request.adoc
request-headers.adoc
request-parameters.adoc
request-body.adoc
http-response.adoc
response-fields.adoc

碎片文件目录只支持两级目录，两级以上的目录文件将不会处理，即如果碎片文件目录为target/generated-snippets， 此目录下有type1和type2两个目录，这算第一层目录，type1和type2会标记为一个大的标题分类， 如果它们下面又有目录，那么这些目录作为第二层目录，为具体的接口的文档目录，生成的html文档目录格式如下:

    type1
        接口1
        接口2
    type2
        接口3
        接口4

maven插件的执行阶段配置在test之前package之后，且在asciidoctor-maven-plugin插件之前(同阶段的插件按配置顺序执行)

maven插件配置示例：

<plugin>
    <groupId>com.spring.rest.maven.plugin</groupId>
    <artifactId>docmerge-maven-plugin</artifactId>
    <version>1.0.0</version>
    <executions>
         <execution>
            <id>merge-docs</id>
            <phase>prepare-package</phase>
            <goals>
               <goal>merge</goal>
            </goals>
         </execution>
    </executions>
</plugin>

配置参数说明:

1.appDir：当前工程目录，默认自动为pom.xml文件所在目录${basedir}

<execution>
    <configuration>     
        <appDir>${basedir}</appDir>
    </configuration>
    <id>merge-docs</id>
     ......
</execution>

2.outputDirectory：合并后的adoc配置文件路径，默认使用${basedir}/src/main/asciidoc

<execution>
    <configuration>     
        <outputDirectory>${basedir}/src/main/asciidoc</outputDirectory>
    </configuration>
    <id>merge-docs</id>
     ......
</execution>

3.sourceDirectory：需要合并的片断文件目录，默认使用${basedir}/target/generated-snippets

<execution>
    <configuration>     
        <sourceDirectory>${basedir}/target/generated-snippets</sourceDirectory>
    </configuration>
    <id>merge-docs</id>
     ......
</execution>

4.docName：生成api配置文件的名称，默认使用openApi.adoc

<execution>
    <configuration>     
        <docName>openApi.adoc</docName>
    </configuration>
    <id>merge-docs</id>
     ......
</execution>

5.title：api标题，默认使用 api列表

<execution>
    <configuration>     
        <title>api列表</title>
    </configuration>
    <id>merge-docs</id>
     ......
</execution>

6.includeDocFiles：只合并部分片断，逗号分隔,如果配置了这一项，那么输出文件中只会有include的这些片断，不能和excludeDocFiles同时配置

<execution>
    <configuration>     
        <includeDocFiles>curl-request.adoc,http-request.adoc</includeDocFiles>
    </configuration>
    <id>merge-docs</id>
     ......
</execution>

7.excludeDocFiles：过滤掉部分片断,逗号分隔,输出的时候，配置中的片断将不会输出

<execution>
    <configuration>     
        <excludeDocFiles>curl-request.adoc,http-request.adoc</excludeDocFiles>
    </configuration>
    <id>merge-docs</id>
     ......
</execution>

Versions

Version
1.0.2 Sep 9, 2019
1.0.1 Sep 7, 2019
1.0.0 Jul 24, 2019