Swagger是一個(gè)用于構(gòu)建生成Restful API文檔的開源框架腾供，主要包括以下工具集：
- Swagger Core Java相關(guān)類庫油湖，生成以及處理Swagger的定義規(guī)范
- 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>
配置類速种，指定掃描路徑以及顯示內(nèi)容
@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("用戶管理系統(tǒng)")
.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="用戶參數(shù)") @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;
}
}
請求參數(shù)實(shí)體，可使用ApiModel以及ApiModelProperty
@ApiModel(value="用戶參數(shù)", description = "用戶參數(shù)描述")
public class UserParam {
@ApiModelProperty(value="用戶名", required = true)
private String name;
private Integer age;
...// set get
}
返回內(nèi)容對象
@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 標(biāo)識(shí)Controller使用swagger.
- @ApiImplicitParam 表示一個(gè)隱式的請求參數(shù)哭当，即請求方法中沒有顯示綁定參數(shù)名稱.
- @ApiImplicitParams 表示隱式參數(shù)列表.
- @ApiModel 描述請求或返回對象的額外信息.
- @ApiModelProperty 描述或者生成ApiModel的成員變量.
- @ApiOperation 描述一個(gè)Http請求方法
- @ApiParam 描述顯示的請求參數(shù).
- @ApiResponse 描述可能的返回對象.
- @ApiResponses 表示返回對象列表.
- @Authorization 申明認(rèn)證信息.
- @ResponseHeader 表示返回頭部信息.
相關(guān)文檔：
