利用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>kongchen@gmail.com</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>
生成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)
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" : "kongchen@gmail.com"
},
"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);
}
注:还有很多细节需要修改。