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>

 添加插件：

            <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>

 

 对项目执行打包命令：mvn clean install

生成的文档：

 


本地访问以下：http://localhost:8999/airline/doc/index.html

airline 为tomcat 上下文路径。



 swagger ui界面：



 具体个人demo，见：

https://github.com/sdcuike/spring-boot-oauth2-demo/tree/blog-2017-06-22/spring-boot-oauth-resource-server