Spring Rest Docs

Spring REST Docs helps you to document RESTful services.
It combines hand-written documentation written with Asciidoctor
and auto-generated snippets produced with Spring MVC Test.

就是用来生成文档的，类似以前学习过的 swagger

官方文档

Quick Start

官方提供了一些例子，个人使用的是 maven，
就尝试了这个 rest-notes-spring-data-rest。

完整代码示例

项目结构

直接复制官方的案例，修改了下包名称。

.
├── pom.xml
└── src
    ├── main
    │   ├── asciidoc
    │   │   ├── api-guide.adoc
    │   │   └── getting-started-guide.adoc
    │   ├── java
    │   │   └── com
    │   │       └── ryo
    │   │           └── spring
    │   │               └── data
    │   │                   └── restdocs
    │   │                       └── notes
    │   │                           ├── Note.java
    │   │                           ├── NoteRepository.java
    │   │                           ├── RestNotesSpringDataRest.java
    │   │                           ├── Tag.java
    │   │                           └── TagRepository.java
    │   └── resources
    │       └── application.properties
    └── test
        └── java
            └── com
                └── ryo
                    └── spring
                        └── data
                            └── restdocs
                                ├── ApiDocumentation.java
                                └── GettingStartedDocumentation.java

• pom.xml

    4.0.0

    spring-data-restdocs


    
        org.springframework.boot
        spring-boot-starter-parent
        2.0.0.M6
        
    

    
        UTF-8
        1.8
        2.0.0.RELEASE
    

    
        
            org.springframework.boot
            spring-boot-starter-data-rest
        
        
            org.springframework.boot
            spring-boot-starter-data-jpa
        

        
            com.h2database
            h2
            runtime
        

        
            org.springframework.boot
            spring-boot-starter-test
            test
        
        
            com.jayway.jsonpath
            json-path
            test
        
        
            org.springframework.restdocs
            spring-restdocs-mockmvc
            test
        
    

    
        
            
                org.springframework.boot
                spring-boot-maven-plugin
            
            
                org.apache.maven.plugins
                maven-surefire-plugin
                
                    
                        **/*Documentation.java
                    
                
            
            
                org.asciidoctor
                asciidoctor-maven-plugin
                1.5.3
                
                    
                        generate-docs
                        prepare-package
                        
                            process-asciidoc
                        
                        
                            html
                            book
                        
                    
                
                
                    
                        org.springframework.restdocs
                        spring-restdocs-asciidoctor
                        ${spring-restdocs.version}
                    
                
            
            
                maven-resources-plugin
                
                    
                        copy-resources
                        prepare-package
                        
                            copy-resources
                        
                        
                            ${project.build.outputDirectory}/static/docs
                            
                                
                                    ${project.build.directory}/generated-docs
                                
                            
                        
                    
                
            
        
    

    
        
            spring-snapshots
            Spring snapshots
            https://repo.spring.io/libs-snapshot
            
                true
            
        
    

    
        
            spring-snapshots
            Spring snapshots
            https://repo.spring.io/libs-snapshot
            
                true

生成文档

直接运行

mvn package

会在 target/generated-docs 目录下生成如下文件：

api-guide.html                  
getting-started-guide.html

效果展示

我们使用浏览器打开 api-guide.html，如下：

2017-12-13-spring-restdocs-demo.png

运行服务

上面是直接浏览静态页面，当然也可以启动一个服务。

直接运行 mvn 插件下的 asciidoctor asciidoctor http。

启动成功后，访问 http://localhost:2000 即可。