Swagger是一个用于构建生成Restful API文档的开源框架，主要包括以下工具集：
- Swagger Core Java相关类库，生成以及处理Swagger的定义规范
- Swagger Editor 使用YAMl格式编写Swagger脚本
- Swagger Codegen 针对各种语言的SDK，用于生成文档
- Swagger UI 基于HTML5的可交互的UI
Springfox是基于Swagger的Api文档生成工具，对SpringMvc支持很好，在Springboot中可以使用Springfox生成在线Api文档
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.6.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.6.0</version>
</dependency>
配置类，指定扫描路径以及显示内容
@Configuration
@EnableSwagger2
@Profile("dev")
//@ComponentScan
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
.paths(PathSelectors.any())
.build()
.globalResponseMessage(RequestMethod.GET,
Lists.newArrayList(new ResponseMessageBuilder().code(500).message("500 ERROR").build()));
}
private ApiInfo apiInfo() {
ApiInfo apiInfo = new ApiInfoBuilder()
.title("用户管理系统")
.description("Restful API文档")
.contact(new Contact("admin","http://xxx.zz.com", "admin@email.com"))
.version("1.0")
.build();
return apiInfo;
}
}
在Controller中使用Swagger注解
@Api(value="用户管理",tags = {"用户管理API"},description = "描述信息")
@Controller
public class UserController {
@ApiOperation(value = "添加用户", notes = "添加用户notes", produces = "application/json")
@ResponseBody
@RequestMapping(value= "/user", method = RequestMethod.POST)
public UserResult user(@ApiParam(value="用户参数") @RequestBody UserParam param) {
UserResult userResult = new UserResult();
userResult.setId("Hello" + param.getName());
userResult.setAge(param.getAge());
return userResult;
}
@ApiOperation("查询用户")
@ApiImplicitParams({
@ApiImplicitParam(name="name",value="用户名",dataType = "string",paramType = "query")
})
@ResponseBody
@RequestMapping(value = "/user", method = RequestMethod.GET)
public UserResult user(HttpServletRequest req) {
String name = req.getParameter("name");
UserResult userResult = new UserResult();
userResult.setId("Hello" + name);
userResult.setAge(100);
return userResult;
}
@ApiOperation("获取用户")
@ResponseBody
@RequestMapping(value= "/user/{name}", method = RequestMethod.GET)
@ApiResponses(value={
@ApiResponse(code=123,message="xxx"),
@ApiResponse(code=405,message="not found")
})
public UserResult user(@ApiParam(value = "用户名") @PathVariable("name") String name, @RequestParam("query") String query) {
UserResult userResult = new UserResult();
userResult.setId("Hello" + name);
userResult.setAge(100);
return userResult;
}
}
请求参数实体，可使用ApiModel以及ApiModelProperty
@ApiModel(value="用户参数", description = "用户参数描述")
public class UserParam {
@ApiModelProperty(value="用户名", required = true)
private String name;
private Integer age;
...// set get
}
返回内容对象
@ApiModel
public class UserResult {
@ApiModelProperty(name="yyy",value="xxx")
private String id;
private Integer age;
...
}
访问Swagger Api： http://localhost:8080/swagger-ui.html
Swagger常用注解：
- @Api 标识Controller使用swagger.
- @ApiImplicitParam 表示一个隐式的请求参数，即请求方法中没有显示绑定参数名称.
- @ApiImplicitParams 表示隐式参数列表.
- @ApiModel 描述请求或返回对象的额外信息.
- @ApiModelProperty 描述或者生成ApiModel的成员变量.
- @ApiOperation 描述一个Http请求方法
- @ApiParam 描述显示的请求参数.
- @ApiResponse 描述可能的返回对象.
- @ApiResponses 表示返回对象列表.
- @Authorization 申明认证信息.
- @ResponseHeader 表示返回头部信息.
相关文档：
