SpringBoot中使用Swagger

转自:https://www.jianshu.com/p/4ad5068dd2ff

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
4000
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 表示返回头部信息.

作者：Ares163
链接：https://www.jianshu.com/p/4ad5068dd2ff
來源：简书
著作权归作者所有。商业转载请联系作者获得授权，非商业转载请注明出处。