swagger editor使用
是一套开源的API设计工具，包括Swagger UI，Swagger Editor等。
Swagger Editor
其中Swagger Editor是个用Angular开发的WEB小程序，它可以让你用YAML来定义你的接口规范，并实时验证和现实成接口文档。
此外，它还可以通过接口文档帮你生成不同框架的服务端和客户端，方便你mock和契约测试。最后导出JSON格式的API规范，通过Swagger UI对外发布。
生成PDF接口文档
现在书写和发布API文档变得快速和轻松，但是有时候，对端希望能有一个离线的WORD或者PDF文档。但当前版本的Swagger Editor并没有导出文档的功能。
转了转github，倒是发现了几个，可以转换为PDF，但是感觉都比较繁琐。
突然想到浏览器可以打印成PDF格式，试验了一下，确实可以。不过接口很多内容都折叠起来了，看不到明细，起不到文档的作用。
不如写句JS，在控制台上运行一下，遍历下所有折叠的节点，然后单击打开。
var node = document.getElementsByClassName('toggle-handle');
for(var i= 0;i& node. i++){
angular.element(node[i]).click();}
这下可以很方便的生成PDF文档了。
阅读(...) 评论()Swagger+Spring mvc生成Restful接口文档 - 竹山一叶 - 博客园
简介&是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。这一次我将从零开始搭建一个工程来演示如何在Spring mvc中整合Swagger生成Restful接口文档。新建工程我们新建一个Maven工程，并添加Web Facet，工程结构如下图所示：添加Maven依赖
4.1.7.RELEASE
org.springframework
spring-webmvc
${spring.version}
org.springframework
spring-core
${spring.version}
com.mangofactory
swagger-springmvc
com.fasterxml.jackson.core
jackson-annotations
${version.jackson}
com.fasterxml.jackson.core
jackson-databind
${version.jackson}
com.fasterxml.jackson.core
jackson-core
${version.jackson}
io.springfox
springfox-swagger2
${swagger.version}
javax.servlet
javax.servlet-api
&!--petstore是官方的一个demo，加入此依赖是为了稍后参考接口描述的编写--&
io.springfox
springfox-petstore
${swagger.version}
添加配置添加一个ApplicationInitializer类，用于配置DispatchServlet启动：在工程中的resources文件夹下新建一个spring的文件夹，并新建一个dispatcher-servlet.xml的spring mvc配置文件，添加如下内容：添加一个SwaggerConfig类，用于配置Swagger接口的说明：新建Controller新建一个GroupController,并编写测试方法：
package yay.apidoc.
import io.swagger.annotations.*;
import org.springframework.stereotype.C
import org.springframework.web.bind.annotation.RequestB
import org.springframework.web.bind.annotation.RequestM
import org.springframework.web.bind.annotation.RequestM
import yay.apidoc.model.UamG
import java.util.LinkedL
import java.util.L
@Controller@RequestMapping(value = "/group", produces = {"application/charset=UTF-8"})
@Api(value = "/group", description = "群组的相关操作")
public class GroupController {@RequestMapping(value = "addGroup", method = RequestMethod.PUT)
@ApiOperation(notes = "addGroup", httpMethod = "POST", value = "添加一个新的群组")
@ApiResponses(value = {@ApiResponse(code = 405, message = "invalid input")})
public UamGroup addGroup(@ApiParam(required = true, value = "group data") @RequestBody UamGroup group) {
@RequestMapping(value = "getAccessibleGroups", method = RequestMethod.GET)
@ApiOperation(notes = "getAccessibleGroups", httpMethod = "GET", value = "获取我可以访问的群组的列表")
public List&UamGroup& getAccessibleGroups() {
UamGroup group1 = new UamGroup();
group1.setGroupId("1");
group1.setName("testGroup1");
UamGroup group2 = new UamGroup();
group2.setGroupId("2");
group2.setName("testGroup2");
List&UamGroup& groupList = new LinkedList&UamGroup&();
groupList.add(group1);
groupList.add(group2);
return groupL
}其中UamGroup的定义如下：
package yay.apidoc.
import io.swagger.annotations.ApiM
import io.swagger.annotations.ApiModelP
public class UamGroup {
@ApiModelProperty(value = "群组的Id", required = true)
private String groupId;
@ApiModelProperty(value = "群组的名称", required = true)
private String
@ApiModelProperty(value = "群组的头像", required = false)
private String
public String getGroupId() {
return groupId;
public void setGroupId(String groupId) {
this.groupId = groupId;
public String getName() {
public void setName(String name) {
this.name =
public String getIcon() {
public void setIcon(String icon) {
this.icon =
}好，目前为止我们的代码已经编写完成，整个工程的目录结构如下：为了让Swagger能够扫描Spring mvc中定义的Controller，我们需要在mvc的配置文件里面定义扫描的路径和相关的bean：添加Swagger ui在GitHub上下载项目，将dist下所有内容拷贝到本地项目apidoc/web下面，结果目录如下图所示：打开目录下的index.html文件，找到代码片段url = "";修改为“/apidoc/v2/api-docs”。为了让网页显示中文，我们可以取消注释以下脚本：为了能够访问index.html页面，我们在dispatcher-servlet.xml中添加如下配置：
mapping="*.html" location="/"/& mapping="/**" location="/"/&好，现在我们启动tomcat来看看效果：解决中文乱码可以看到，我们写在方法上说明居然成了乱码，为了解决这个问题，我们新建一个转换类：
package yay.apidoc.
import com.fasterxml.jackson.annotation.JsonInclude;
import com.fasterxml.jackson.databind.*;
import org.springframework.http.HttpInputMessage;
import org.springframework.http.converter.HttpMessageNotReadableException;
import org.springframework.http.converter.json.MappingJackson2HttpMessageConverter;
import java.io.IOException;
import java.text.SimpleDateFormat;
public class MappingJacksonHttpMessageConverterEx extends MappingJackson2HttpMessageConverter {
private ObjectMapper objectMapper = new ObjectMapper();
public MappingJacksonHttpMessageConverterEx() {
DeserializationConfig deserializationConfig = objectMapper.getDeserializationConfig()
.without(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES);
objectMapper.setConfig(deserializationConfig);
SerializationConfig serializationConfig = objectMapper.getSerializationConfig()
.without(SerializationFeature.FAIL_ON_EMPTY_BEANS);
objectMapper.setConfig(serializationConfig);
objectMapper.setDateFormat(new SimpleDateFormat("yyyy-MM-dd HH:mm:ss"));
objectMapper.setSerializationInclusion(JsonInclude.Include.NON_NULL);
objectMapper.configure(SerializationFeature.ORDER_MAP_ENTRIES_BY_KEYS,true);
setObjectMapper(objectMapper);
@Overrideprotected Object readInternal(Class&?& clazz, HttpInputMessage inputMessage)
throws IOException, HttpMessageNotReadableException {
JavaType javaType = getJavaType(null, clazz);
return this.objectMapper.readValue(inputMessage.getBody(), javaType);
}然后修改dispatcher-servlet.xml中的mvc:annotation-driven配置节：
&!-- Standard xml based mvc config--&
class="org.springframework.http.converter.StringHttpMessageConverter"
name="supportedMediaTypes"
text/charset=UTF-8
class="yay.apidoc.converter.MappingJacksonHttpMessageConverterEx"
class="org.springframework.http.converter.ResourceHttpMessageConverter"
我们再来看看效果:来源：&1：认识Swagger
Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使和文件系统作为以同样的速度来更新。文件的方法，参数和紧密集成到服务器端的代码，允许API来始终保持同步。
&&&&1.&的文档在线自动生成。
&&&&2.&功能测试。
&Swagger是一组开源，其中主要要项目如下：
1.&& Swagger-tools:提供各种与Swagger进行集成和交互的工具。例如模式检验、Swagger 1.2文档转换成Swagger 2.0文档等功能。
2.&& Swagger-core: 用于/Scala的的Swagger实现。与JAX-RS(Jersey、Resteasy、CXF...)、Servlets和Play框架进行集成。
3.&& Swagger-js: 用于的Swagger实现。
4.&& Swagger-node-express: Swagger模块，用于node.js的Express web应用框架。
5.&& Swagger-ui：一个无依赖的HTML、JS和CSS集合，可以为Swagger兼容API生成优雅文档。
6.&& Swagger-codegen：一个模板驱动引擎，通过分析用户Swagger资源声明以各种语言生成客户端代码。
请根据实际情况自行更改。
&dependency&
&&&&&groupId&io.springfox&/groupId&
&&& &artifactId&springfox-swagger2&/artifactId&
&&& &&2.2.2&/version&
&/dependency&
&dependency&
&&& &groupId&io.springfox&/groupId&
&&& &artifactId&springfox-swagger-ui&/artifactId&
&&& &version&2.2.2&/version&
&/dependency&
3：创建Swagger2配置类
在Application.java同级创建Swagger2的配置类Swagger2
com.swaggerT
import org.springframework.context.annotation.B
import org.springframework.context.annotation.C
import springfox.documentation.builders.ApiInfoB
import springfox.documentation.builders.PathS
import springfox.documentation.builders.RequestHandlerS
import springfox.documentation.service.ApiI
import springfox.documentation.spi.DocumentationT
import springfox.documentation.spring.web.plugins.D
import springfox.documentation.swagger2.annotations.EnableSwagger2;
* Swagger2配置类
* 在与spring boot集成时，放在与Application.java同级的目录下。
* 通过@Configuration注解，让Spring来加载该类配置。
* 再通过@EnableSwagger2注解来启用Swagger2。
@Configuration
@EnableSwagger2
public class Swagger2 {
* 创建API应用
* apiInfo() 增加API相关信息
* 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，
* 本例采用指定扫描的包路径来定义指定要建立API的目录。
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.apis(RequestHandlerSelectors.basePackage("com.swaggerTest.controller"))
.paths(PathSelectors.any())
* 创建该API的基本信息（这些基本信息会展现在文档页面中）
* 访问地址：http://项目实际地址/swagger-ui.html
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Spring Boot中使用Swagger2构建RESTful APIs")
.description("更多请关注")
.termsOfServiceUrl("")
.contact("sunf")
.version("1.0")
如上代码所示，通过createRestApi函数创建Docket的Bean之后，apiInfo()用来创建该Api的基本信息（这些基本信息会展现在文档页面中）。
4：添加文档内容
在完成了上述配置后，其实已经可以生产文档内容，但是这样的文档主要针对请求本身，描述的主要来源是函数的命名，对用户并不友好，我们通常需要自己增加一些说明来丰富文档内容。
Swagger使用的注解及其说明：
@Api：用在类上，说明该类的作用。
@ApiOperation：注解来给API增加方法说明。
@ApiImplicitParams : 用在方法上包含一组参数说明。
@ApiImplicitParam：用来注解来给方法入参增加说明。
@ApiResponses：用于表示一组响应
@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
&&&&l&& code：数字，例如400
&&&&l&& ：信息，例如"请求参数没填好"
&&&&l&& response：抛出异常的类&&&
@ApiModel：描述一个Model的信息（一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候）
&&&&l&& @ApiModelProperty：描述一个model的属性
注意：@ApiImplicitParam的参数说明：
paramType：指定参数放在哪个地方
header：请求参数放置于Request Header，使用@RequestHeader获取 query：请求参数放置于请求地址，使用@RequestParam获取 path：（用于restful接口）--&请求参数的获取：@PathVariable body：（不常用） form（不常用）
name：参数名
dataType：参数类型
required：参数是否必须传
true | false
value：说明参数的意思
defaultValue：参数的默认值
package com.swaggerTest.
import org.springframework.stereotype.C
import org.springframework.util.StringU
import org.springframework.web.bind.annotation.RequestM
import org.springframework.web.bind.annotation.RequestM
import org.springframework.web.bind.annotation.RequestP
import org.springframework.web.bind.annotation.ResponseB
import io.swagger.annotations.A
import io.swagger.annotations.ApiImplicitP
import io.swagger.annotations.ApiImplicitP
import io.swagger.annotations.ApiO
* 一个用来测试swagger注解的控制器
* 注意@ApiImplicitParam的使用会影响运行，如果使用不当可能造成控制器收不到消息
* @author SUNF
@Controller
@RequestMapping("/say")
@Api(value = "https://my.oschina.net/dlam/blog/SayController|一个用来测试swagger注解的控制器")
public class SayController {
@ResponseBody
@RequestMapping(value ="https://my.oschina.net/getUserName", method= RequestMethod.GET)
@ApiOperation(value="https://my.oschina.net/dlam/blog/根据用户编号获取用户姓名", notes="test: 仅1和2有正确返回")
@ApiImplicitParam(paramType="query", name = "userNumber", value = "https://my.oschina.net/dlam/blog/用户编号", required = true, dataType = "Integer")
public String getUserName(@RequestParam Integer userNumber){
if(userNumber == 1){
return "张三丰";
else if(userNumber == 2){
return "慕容复";
return "未知";
@ResponseBody
@RequestMapping("/Password")
@ApiOperation(value="https://my.oschina.net/dlam/blog/修改用户密码", notes="根据用户id修改密码")
@ApiImplicitParams({
@ApiImplicitParam(paramType="query", name = "userId", value = "https://my.oschina.net/dlam/blog/用户ID", required = true, dataType = "Integer"),
@ApiImplicitParam(paramType="query", name = "password", value = "https://my.oschina.net/dlam/blog/旧密码", required = true, dataType = "String"),
@ApiImplicitParam(paramType="query", name = "newPassword", value = "https://my.oschina.net/dlam/blog/新密码", required = true, dataType = "String")
public String updatePassword(@RequestParam(value="https://my.oschina.net/dlam/blog/userId") Integer userId, @RequestParam(value="https://my.oschina.net/dlam/blog/password") String password,
@RequestParam(value="https://my.oschina.net/dlam/blog/newPassword") String newPassword){
if(userId &= 0 || userId & 2){
return "未知的用户";
if(StringUtils.isEmpty(password) || StringUtils.isEmpty(newPassword)){
return "密码不能为空";
if(password.equals(newPassword)){
return "新旧密码不能相同";
return "密码修改成功!";
完成上述代码添加上，启动Spring Boot程序，访问：http://:8080/swagger-ui.html
如上图，可以看到暴漏出来的控制器信息，点击进入可以看到详细信息。
两个注意点：
1.& paramType会直接影响程序的运行期，如果paramType与方法参数获取使用的注解不一致，会直接影响到参数的接收。
使用Sawgger UI进行测试，接收不到！
2. &还有一个需要注意的地方：
Conntroller中定义的方法必须在@RequestMapper中显示的指定RequestMethod类型，否则SawggerUi会默认为全类型皆可访问， API列表中会生成多条项目。
如上图：updatePassword()未指定requestMethod，结果生成了7条API信息。所以如果没有特殊需求，建议根据实际情况加上requestMethod。
5：Swagger UI面板说明
/springbootswagger2/
http://blog.csdn.net/jia20003/article/details/
Swagger官网 ：http://swagger.io/
Spring Boot & Swagger UI ： /spring-boot-swagger-ui/
Github：/swagger-api/swagger-core/wiki/Annotations