spring boot rest接口自动生成文档（包含swagger）
spring boot rest接口自动生成文档（包含swagger）
写接口免不了写接口文档，但是当文档与代码分开独立演进的时候，会发生很多不同步的问题。
接口描述与代码同步的最简便的方式就是利用java doc，改代码或参数的时候，顺便把java doc也更新了。
所以，我们可以利用java doc自动生成文档。
组件enunciate 就是这种方式来自动生成文档，而且生成了一份html文档，也包括swagger ui。
下面例子介绍了此组件的maven插件使用方式，方便自动生成文档，打包jar包内。
目前为止，最新版本：
<enunciate.version>2.9.1</enunciate.version>
不过，支持enum，和 oauth2（swagger）不是太好，作者正在改进。
本项目以spring boot：
pom 添加依赖：
<dependency>
<groupId>com.webcohesion.enunciate</groupId>
<artifactId>enunciate-core</artifactId>
<version>${enunciate.version}</version>
</dependency>
<dependency>
<groupId>com.webcohesion.enunciate</groupId>
<artifactId>enunciate-core-annotations</artifactId>
<version>${enunciate.version}</version>
</dependency>
<groupId>com.webcohesion.enunciate</groupId>
<artifactId>enunciate-core</artifactId>
<version>${enunciate.version}</version>
</dependency>
<dependency>
<groupId>com.webcohesion.enunciate</groupId>
<artifactId>enunciate-core-annotations</artifactId>
<version>${enunciate.version}</version>
</dependency>
添加插件：
<plugin>
<groupId>com.webcohesion.enunciate</groupId>
<artifactId>enunciate-maven-plugin</artifactId>
<version>${enunciate.version}</version>
<executions>
<execution>
<goals>
<goal>assemble</goal>
</goals>
<configuration>
<docsDir>${project.basedir}/src/main/resources/static/doc</docsDir>
<configFile>enunciate.xml</configFile>
</configuration>
</execution>
</executions>
<dependencies>
<dependency>
<groupId>com.webcohesion.enunciate</groupId>
<artifactId>enunciate-lombok</artifactId>
<version>${enunciate.version}</version>
</dependency>
</dependencies>
</plugin>
<groupId>com.webcohesion.enunciate</groupId>
<artifactId>enunciate-maven-plugin</artifactId>
<version>${enunciate.version}</version>
<executions>
<execution>
<goals>
<goal>assemble</goal>
</goals>
<configuration>
<docsDir>${project.basedir}/src/main/resources/static/doc</docsDir>
<configFile>enunciate.xml</configFile>
</configuration>
</execution>
</executions>
<dependencies>
<dependency>
<groupId>com.webcohesion.enunciate</groupId>
<artifactId>enunciate-lombok</artifactId>
<version>${enunciate.version}</version>
</dependency>
</dependencies>
</plugin>
因为项目中使用了lombok，所以配置了enunciate-lombok，上面enunciate.xml为enunciate的配置文件，
<docsDir>${project.basedir}/src/main/resources/static/doc</docsDir>为文档生成目录，放到此目录下，spring
boot静态资源可以正常访问。
enunciate.xml 的配置内容：
<enunciate xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://enunciate.webcohesion.com/schemas/enunciate-2.2.0.xsd">
<title>航空文档 作者: xxxx</title>
<copyright>https://www.xxx.com</copyright>
<application root="/airline"/>
<api-classes>
<include pattern="com.xxx.airline.controller.**"/>
</api-classes>
<modules>
<jackson1 disabled="true"/>
</modules>
</enunciate>
xsi:noNamespaceSchemaLocation="http://enunciate.webcohesion.com/schemas/enunciate-2.2.0.xsd">
<title>航空文档 作者: xxxx</title>
<copyright>https://www.xxx.com</copyright>
<application root="/airline"/>
<api-classes>
<include pattern="com.xxx.airline.controller.**"/>
</api-classes>
<modules>
<jackson1 disabled="true"/>
</modules>
</enunciate>
对项目执行打包命令：mvn clean install
生成的文档：
本地访问以下：http://localhost:8999/airline/doc/index.html
airline 为tomcat 上下文路径。
swagger ui界面：
具体个人demo，见：