利用Swagger Maven Plugin生成Rest API文档

利用Swagger Maven Plugin生成Rest API文档

Swagger Maven Plugin

This plugin enables your Swagger-annotated project to generate Swagger specs and customizable, templated static documents during the maven build phase. Unlike swagger-core, swagger-maven-plugin does not actively serve the spec with the rest of the application; it generates the spec as a build artifact to be used in downstream Swagger tooling.

预知详情，请到官网：

https://github.com/kongchen/swagger-maven-plugin

例子

在pom中添加插件：

 <build>        <plugins>            <plugin>                <groupId>org.apache.maven.plugins</groupId>                <artifactId>maven-javadoc-plugin</artifactId>                <configuration>                    <charset>UTF-8</charset>                    <docencoding>UTF-8</docencoding>                    <failOnError>false</failOnError>                </configuration>            </plugin>            <plugin>                <groupId>com.github.kongchen</groupId>                <artifactId>swagger-maven-plugin</artifactId>                <configuration>                    <apiSources>                        <apiSource>                            <springmvc>false</springmvc>                            <locations>com.doctor.demo</locations>                            <schemes>http,https</schemes>                            <host>petstore.swagger.wordnik.com</host>                            <basePath>/api</basePath>                            <info>                                <title>Swagger Maven Plugin Sample</title>                                <version>v1</version>                                <description>This is a sample for swagger-maven-plugin</description>                                <termsOfService>                                    http://www.github.com/kongchen/swagger-maven-plugin                                </termsOfService>                                <contact>                                    <email>[e-mail]</email>                                    <name>Kong Chen</name>                                    <url>http://kongch.com</url>                                </contact>                                <license>                                    <url>http://www.apache.org/licenses/LICENSE-2.0.html</url>                                    <name>Apache 2.0</name>                                </license>                            </info>                            Support classpath or file absolute path here. 1) classpath e.g: "classpath:/markdown.hbs", "classpath:/templates/hello.html" 2) file e.g: "${basedir}/src/main/resources/markdown.hbs", "${basedir}/src/main/resources/template/hello.html"                            <templatePath>${basedir}/templates/strapdown.html.hbs</templatePath>                            <outputPath>${basedir}/generated/document.html</outputPath>                            <swaggerDirectory>generated/swagger-ui</swaggerDirectory>                        </apiSource>                    </apiSources>                </configuration>                <executions>                    <execution>                        <phase>compile</phase>                        <goals>                            <goal>generate</goal>                        </goals>                    </execution>                </executions>            </plugin>                    </plugins>    </build>

用到的插件模版请到https://github.com/swagger-maven-plugin/swagger-maven-example 

下载。

生成API json文件，并在swagger-ui中显示：

 1.在该项目下执行mvn clean compile，得到generated/swagger-ui/swagger.json.
 
 2.下载https://github.com/swagger-api/swagger-ui/tree/master/dist 编译后的版本。
 
 3.swagger.json拷贝到dist目录下。然后把dist放到tomcat webapp目录下。（可以把本项目目录下到dist之间copy到tomcat下）。
 
 4.启动tomcat。端口配置为8888。
 
 5.打开http://localhost:8888/dist/ swagger-ui页面。
 
 6.在swagger-ui页面顶端输入地址http://localhost:8888/dist/swagger.json，即可看到rest接口文档。
 
 7.截图（rest.png)

附录：生成的json文件内容

 

{  "swagger" : "2.0",  "info" : {    "description" : "This is a sample for swagger-maven-plugin",    "version" : "v1",    "title" : "Swagger Maven Plugin Sample",    "termsOfService" : "http://www.github.com/kongchen/swagger-maven-plugin",    "contact" : {      "name" : "Kong Chen",      "url" : "http://kongch.com",      "email" : "[e-mail]"    },    "license" : {      "name" : "Apache 2.0",      "url" : "http://www.apache.org/licenses/LICENSE-2.0.html"    }  },  "host" : "petstore.swagger.wordnik.com",  "basePath" : "/api",  "tags" : [ {    "name" : "hello service"  } ],  "schemes" : [ "http", "https" ],  "paths" : {    "/hello/w" : {      "post" : {        "tags" : [ "hello service" ],        "summary" : "test hello method",        "description" : "note",        "operationId" : "hello",        "consumes" : [ "application/json" ],        "produces" : [ "application/json" ],        "parameters" : [ {          "in" : "body",          "name" : "body",          "description" : "welcomDto object",          "required" : true,          "schema" : {            "$ref" : "#/definitions/WelcomeDto"          }        } ],        "responses" : {          "200" : {            "description" : "successful operation",            "schema" : {              "$ref" : "#/definitions/WelcomeResponseDto"            }          }        }      }    }  },  "definitions" : {    "WelcomeDto" : {      "type" : "object",      "properties" : {        "name" : {          "type" : "string"        },        "age" : {          "type" : "integer",          "format" : "int32"        }      }    },    "WelcomeResponseDto" : {      "type" : "object",      "properties" : {        "content" : {          "type" : "string"        }      }    }  }}

接口描述：

package com.doctor.demo.service;import javax.ws.rs.Consumes;import javax.ws.rs.POST;import javax.ws.rs.Path;import javax.ws.rs.Produces;import javax.ws.rs.core.MediaType;import com.doctor.demo.common.dto.WelcomeDto;import com.doctor.demo.common.dto.WelcomeResponseDto;import io.swagger.annotations.Api;import io.swagger.annotations.ApiOperation;import io.swagger.annotations.ApiParam;import io.swagger.annotations.ApiResponse;/** * @author sdcuike * * @time 2016年1月25日 下午11:07:44 */@Api(value = "hello", tags = "hello service")@Path("hello")public interface HelloRestService {    /**     * 老接口方式（DTO)     *      * @param welcomDto     * @return     */    @ApiOperation(value = "test hello method", notes = "note")    @POST    @Path("w")    @Consumes({ MediaType.APPLICATION_JSON })    @Produces({ MediaType.APPLICATION_JSON })    @ApiResponse(message = "ok", code = 200)    WelcomeResponseDto hello(@ApiParam(value = "welcomDto object", required = true) WelcomeDto welcomDto);}

注：还有很多细节需要修改。