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,见: