Swagger API实践

实践过程

一、引入依赖

    io.springfox
    springfox-swagger2
    ${springfox.version}


    io.springfox
    springfox-swagger-ui
    ${springfox.version}

    false
    false
    com.huawei.olap.mini.consumer.ConsumerApplication
    1.6.0-SNAPSHOT
    yyyyMMddHHmmss
    ${project.version}.${maven.build.timestamp}


    1.2.0
    ${project.basedir}/src/docs/asciidoc

    ${project.build.directory}/swagger
    ${project.build.directory}/asciidoc/snippets
    ${project.build.directory}/asciidoc/generated
    ${project.build.directory}/asciidoc/html
    ${project.build.directory}/asciidoc/pdf

    ${project.build.directory}/swagger/swagger.json
    2.9.6
    2.9.2

二、Controller中使用注解添加API文档

 

@RequestMapping(value = "/query", method = RequestMethod.POST)
@ApiOperation( value = "消费方法", notes = "此方法的详细情况")
@ApiResponses(value = {
        @ApiResponse(code = 400, message = "Invalid ID supplied"),
        @ApiResponse(code = 404, message = "Pet not found")}
)
public String consumer(@RequestBody ConsumerSQLRequest request) {
    logger.info("Enter consumer query.");
    String database = request.getDatabase();
    String sql = request.getSql();
    String result = consumerService.query(database, sql);
    return result;
}

 

 

 

三、自动生成yaml文件和json文件

pom中可以对swagger一些必要信息进行配置。比如包扫描路径。开发人员信息之类的

 

 

    swagger
    
        
            
                org.apache.maven.plugins
                maven-compiler-plugin
                
                    1.8
                    1.8
                    UTF-8
                
            
            
                org.apache.maven.plugins
                maven-surefire-plugin
                
                    
                        ${swagger.output.dir}
                        
                        ${swagger.snippetOutput.dir}
                        
                    
                
            
            
                com.github.kongchen
                swagger-maven-plugin
                3.1.7
                
                    
                        
                            true
                            
                                com.huawei.olap.mini.consumer.controller
                            
                            
                                http
                                https
                            
                            localhost:8800
                            /
                            
                                
                                1.00
                                
                                    This is a sample.
                                
                                
                                    http://www.github.com/kongchen/swagger-maven-plugin
                                
                                
                                    [email protected]
                                    wss wolf
                                    http://www.wushangshang.com
                                
                                
                                    http://www.apache.org/licenses/LICENSE-2.0.html
                                    Apache 2.0
                                
                            
                            ${basedir}/generated/document.html
                            json,yaml
                            ${project.build.directory}/swagger
                            true
                        
                    
                
                
                    
                        swagger-build
                        compile
                        
                            generate
                        
                    
                
                
                    
                    
                        io.swagger
                        swagger-hibernate-validations
                        1.5.14
                    
                
            
        

    

 

 

 

pom中配置maven插件，在terminal中执行 mvn package -Pswagger。就可以成功生成yaml文件。

 

 

如果遇到 No compiler is provided in this environment. Perhaps you are running on a JRE rather than a JDK? 这个错误，尝试执行idea侧边的lifecycle中clean，package。执行过一遍再继续执行命令 mvn package -Pswagger就可以成功

 

 

执行成功后会根据pom中插件的配置，在相应路径下生成json和yaml文件.   

${basedir}/generated/document.html在这个目录生成文件

 

 

四、生成html文档

上一步执行完生成的json文件，接下来再继续使用另一个插件需要用到它来生成html文件。 分为两个步骤，先后执行两个插件，顺序不可颠倒。

第一步 配置swagger2markup插件

 

 

 

    io.github.swagger2markup
    swagger2markup-maven-plugin
    ${swagger2markup.version}
    
        
            io.github.swagger2markup
            swagger2markup-import-files-ext
            ${swagger2markup.version}
        
        
            io.github.swagger2markup
            swagger2markup-spring-restdocs-ext
            ${swagger2markup.version}
        
    
    
        ${swagger.input}
        ${generated.asciidoc.directory}
        
            ASCIIDOC
            true
        
    
    
        
            test
            
                convertSwagger2markup
            
        
    

 

 

 

 

生成asciidoc文件，在pom中配置生成地址，生成最终文档的索引文件。这些文件会被下一个插件使用，如何执行这个插件呢，在idea旁边的maven窗口，找到这个插件双击就可。

 

 

第二步 配置asciidoctor插件，这个插件来生成pdf或者html，这里还需要一个index.adoc文件，这个插件需要上面的那个index.adoc文件和上一个插件生成的那几个文件。去这个目录

${asciidoctor.input.directory}读取index.asc文件，再执行插件命令，在旁边maven栏，process-asciidoc.

 

 

此时再生成的这个index.html就是正确的了。