This plugin helps you generate API documents in build phase according to customized output templates.
Latest version 1.1.1 is availabe in central repository
<?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">
…
<dependencies>
…
</dependencies>
<build>
<plugins>
...
<plugin>
<groupId>com.github.kongchen</groupId>
<artifactId>swagger-maven-plugin</artifactId>
<version>1.1.1</version>
<configuration>
<apiSources>
<apiSource>
<locations>com.foo.bar.apis;com.foo.bar.apis.internal.Resource</locations>
<apiVersion>v1</apiVersion>
<basePath>http://www.example.com</basePath>
<outputTemplate>
https://raw.github.com/kongchen/api-doc-template/master/v1.1/markdown.mustache
</outputTemplate>
<outputPath>generated/strapdown.html</outputPath>
<withFormatSuffix>false</withFormatSuffix>
<swaggerDirectory>generated/apidocs</swaggerDirectory>
</apiSource>
</apiSources>
</configuration>
<executions>
<execution>
<phase>compile</phase>
<goals>
<goal>generate</goal>
</goals>
</execution>
</executions>
</plugin>
...
</plugins>
</build>
...
</project>- One
apiSourcecan be considered as a set of APIs for oneapiVersionin API'sbasePath. - Java classes containing Swagger's annotation
@Api, or Java packages containing those classes can be configured inlocations, using;as the delimiter. outputTemplateis the path of the mustache template file.
It supports a remote path such as https://raw.github.com/kongchen/api-doc-template/master/v1.1/markdown.mustache but local file is highly recommanded because:
> 1. You can modify the template to match your requirement easily.
> 2. Mustache can use `>localfile` to inculde a local file.
>E.g: The template https://raw.github.com/kongchen/api-doc-template/master/v1.1/strapdown.html.mustache includes
[`markdown.mustache`](https://raw.github.com/kongchen/api-doc-template/master/v1.1/markdown.mustache) by this way,
to use `strapdown.html.mustache` you should put `markdown.mustache` in your local path first.
outputPathis the path of your output file, not existed parent directory of the file will be created.- If
swaggerDirectoryis configured, the plugin will also generate a Swagger resource listing suitable for feeding to swagger-ui. withFormatSuffixindicates if you need Swagger's .{format} suffix in API's path. Default: false
You can specify several apiSources with different api versions and base paths.
There's a standalone project for the template files, see more details there and welcome to pull.
Check out this sample project to see how this happens.