spring boot rest接口自动生成文档（包含swagger）

spring boot rest接口自动生成文档（包含swagger）

     写接口免不了写接口文档，但是当文档与代码分开独立演进的时候，会发生很多不同步的问题。

        接口描述与代码同步的最简便的方式就是利用java doc，改代码或参数的时候，顺便把java doc也更新了。

      所以，我们可以利用java doc自动生成文档。

      组件enunciate 就是这种方式来自动生成文档，而且生成了一份html文档，也包括swagger ui。

        下面例子介绍了此组件的maven插件使用方式，方便自动生成文档，打包jar包内。

    目前为止，最新版本：

<enunciate.version>2.9.1enunciate.version>

   不过，支持enum，和 oauth2（swagger）不是太好，作者正在改进。

  本项目以spring boot：

   pom 添加依赖：

       
            com.webcohesion.enunciate
            enunciate-core
            ${enunciate.version}
       
       
            com.webcohesion.enunciate
            enunciate-core-annotations
            ${enunciate.version}
       

 添加插件：

           
                com.webcohesion.enunciate
                enunciate-maven-plugin
                ${enunciate.version}
               
                   
                       
                            assemble
                       
                       
                            ${project.basedir}/src/main/resources/static/doc
                            enunciate.xml
                       
                   
               
               
                   
                        com.webcohesion.enunciate
                        enunciate-lombok
                        ${enunciate.version}
                   
               
           

       因为项目中使用了lombok，所以配置了enunciate-lombok，上面enunciate.xml为enunciate的配置文件，

    ${project.basedir}/src/main/resources/static/doc为文档生成目录，放到此目录下，spring boot静态资源可以正常访问。

    enunciate.xml 的配置内容：

           xsi:noNamespaceSchemaLocation="http://enunciate.webcohesion.com/schemas/enunciate-2.2.0.xsd">


   
    https://www.xxx.com
   


   
       
   
   
       
   

 

 对项目执行打包命令：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