Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。当项目前后端分离或者后台给APP提供接口时，这时候使用swagger来管理接口还是很方便的，省去了很多开发人员对接的时间。
先来个图展示下效果
image.png
接下来开始实现这个功能
- 首先pom.xml引入依赖
<!-- Swagger2强大RESTful API文档 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.2.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.2.2</version>
</dependency>
<!-- Swagger2强大RESTful API文档 -->
- 然后开始创建Swagger的配置文件
@Configuration
@EnableSwagger2
public class Swagger2 {
// Swagger2默认将所有的Controller中的RequestMapping方法都会暴露，
// 然而在实际开发中，我们并不一定需要把所有API都提现在文档中查看，这种情况下，使用注解
// @ApiIgnore来解决，如果应用在Controller范围上，则当前Controller中的所有方法都会被忽略，
// 如果应用在方法上，则对应用的方法忽略暴露API
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.daiwei.project")) //指向你的包
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Sword项目的RESTful APIs")
.description("Sword项目的RESTful APIs")
.termsOfServiceUrl("http://www.jianshu.com/u/61959c6c46fa")
.contact("David inner")
.version("2.0")
.build();
}
}
- 最后去你具体的controller配置,就简单举两个列子
/**
* 删除
* 方法功能说明
* 创建时间 2017年7月25日 下午10:59:17
* 开发者 david
* @参数： @param ids
* @参数： @return
* @return： Result
*/
@ApiOperation(value = "删除企业", notes = "根据url的ids来指定删除对象或者对象集")
@ApiImplicitParam(name = "ids", value = "企业ids", required = true, dataType = "String")
@ResponseBody
@RequestMapping(value = "/delete",method=RequestMethod.DELETE)
public Result delete(String ids) {
List<Long> list = Utils.stringToLongList(ids, ",");
for(Long id:list){
companyService.companyDao.delete(id);
}
return Result.ok("删除成功!");
}
/**
* 保存企业
* @param company
* @return
*/
@ApiOperation(value = "保存/修改企业", notes = "根据Company对象操作企业")
@ApiImplicitParam(name = "company", value = "企业详细实体user", required = true, dataType = "Company")
@ResponseBody
@RequestMapping(value="/save",method=RequestMethod.POST)
public Result save(Company company){
return companyService.save(company);
}
- 访问地址
http://localhost:8088/sword2.0/swagger-ui.html
因为我配置了自己的context-path,具体项目具体看
image.png
这里如果不加@ApiIgnore的话会把你指向的包里面的controller全部生成展示出来，这样swagger2就被完美的集成到你的项目中了。最后罗列下关于swagger的一些注解
@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述
@ApiModel：用对象来接收参数
@ApiProperty：用对象接收参数时，描述对象的一个字段
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiIgnore：使用该注解忽略这个API
@ApiClass
@ApiError
@ApiErrors
@ApiParamImplicit
@ApiParamsImplicit
