Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件或插件。是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。方便接口调用者查看调试,开发者不用自己写个文档。
使用方法:
1.maven引入依赖:
<dependency>
<groupId>com.mangofactory</groupId>
<artifactId>swagger-springmvc</artifactId>
<version>1.0.2</version>
</dependency>
2.使用springboot或springmvc实例化
package com.lifeng.config;
import com.mangofactory.swagger.configuration.SpringSwaggerConfig;
import com.mangofactory.swagger.models.dto.ApiInfo;
import com.mangofactory.swagger.plugin.EnableSwagger;
import com.mangofactory.swagger.plugin.SwaggerSpringMvcPlugin;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.stereotype.Component;
/**
* Created by lifeng
* 2017/12/11 17:33
*/
@EnableSwagger
@Component //如何使用springmvc,在spring配置文件实例化<bean class="xxxx">
public class MySwaggerConfig {
@Autowired
private SpringSwaggerConfig springSwaggerConfig;
@Bean(name="springSwaggerConfig")//如何使用springmvc,在spring配置文件实例化
public SpringSwaggerConfig getSpringSwaggerConfig(){
return new SpringSwaggerConfig();
}
@Bean
public SwaggerSpringMvcPlugin customImplementation(){
//和springmvc集成插件
return new SwaggerSpringMvcPlugin(this.springSwaggerConfig).apiInfo(apiInfo())
.includePatterns(".*?");
}
private ApiInfo apiInfo(){
ApiInfo apiInfo = new ApiInfo(
"springmvc搭建swagger(标题)",
"spring-API swagger测试(描述)",
"(服务的url)",
"[email protected]",
"license",
"license URL");
return apiInfo;
}
}
3.在controller中使用相关注解即可
package com.lifeng.controller;
import com.mangofactory.swagger.annotations.ApiIgnore;
import com.wordnik.swagger.annotations.Api;
import com.wordnik.swagger.annotations.ApiOperation;
import com.wordnik.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
/**
* Created by lifeng
* 2017/12/11 16:36
*/
@RestController
@RequestMapping("/user")
@Api(value="user",description = "用户相关api")
public class UserController {
@RequestMapping(value = "getUserInfo")
@ApiOperation(value="通过ID获取用户信息",httpMethod="GET",notes="通过ID获取用户信息")
public String getUser(@ApiParam(required=true,value="用户ID",name="id")
@RequestParam(value="id") Integer id,
@ApiParam(required=true,value="用户姓名",name="name")
@RequestParam(value="name") String name
){
System.out.println("用户ID:"+id+",姓名:"+name);
return "{'name':'张三','age':22}";
}
@RequestMapping(value = "addUser",consumes = "application/json",produces = {"application/xml"})
@ApiOperation(value="添加用户信息",httpMethod="POST",notes="添加用户信息json",response=String.class)
public String addUser(@ApiParam(required=true,value="用户信息",name="params")
@RequestParam(value="params") String params){
System.out.println("请求参数:"+params);
return "<xml><code>success</code><msg>成功</msg></xml>";
}
@RequestMapping(value = "deleteUser")
@ApiIgnore
public String delete(){
return "ok";
}
}
4.swagger常用注解参考:
http://www.jianshu.com/p/12f4394462d5
https://www.cnblogs.com/yuan951/p/7243383.html
5.swagger-ui的可视化的界面:
https://github.com/swagger-api/swagger-ui/ 选择 2.x的版本,我之前下了最新版的弄了一天都行,后来才知道是版本的问题,我也是醉了。
解压后将dist文件夹中所有的文件拷贝到webapp/swagger这里的swagger是作者自定义的你可以写为自己创建的目录。
修改index.html中的 http://petstore.swagger.wordnik.com/v2/swagger.json修改为自己项目路径+api-docs,例如:
http://localhost:8080/swagger/api-docs:(我的项目在ROOT下放着,所以不需要项目名称了)
5.浏览器访问http://localhost:8080/swagger/index.html
并在搜索框输入http://localhost:8080/api-docs