https://www.cnblogs.com/jtlgb/p/8532433.html
1 手写Api文档的几个痛点:
- 文档需要更新的时候,需要再次发送一份给前端,也就是
文档更新交流不及时
- 接口
返回结果不明确
不能直接在线测试接口
,通常需要使用工具,比如postman
接口文档太多,不好管理
Swagger也就是为了解决这些问题
,直接生成接口文档的方式。当然也不能说Swagger就一定是完美的,当然也有缺点,最明显的就是代码移入性比较强。
2 swagger2的使用
2.1 依赖
compile "io.springfox:springfox-swagger2:2.7.0"
compile 'io.springfox:springfox-swagger-ui:2.7.0'
2.2 配置类
@Configuration
注解,让Spring来加载该类配置
。再通过@EnableSwagger2
注解来启用Swagger2
。
其实这个配置类,只要了解具体能配置哪些东西就好了,毕竟这个东西配置一次之后就不用再动了。 特别要注意的是里面配置了api文件也就是controller包的路径,不然生成的文档扫描不到接口。
注解 @EnableSwagger2 表示开启Swagger
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket buildDocket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(buildApiInf())
.select().apis(RequestHandlerSelectors.basePackage("com.system.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo buildApiInf() {
return new ApiInfoBuilder()
//页面标题
.title("内蒙古医院探视信息管理项目")
//版本号
.version("1.0.2")
//描述
.build();
}
}
用**@Configuration注解该类,等价于XML中配置beans**;用**@Bean标注方法等价于XML中配置bean**。
2.3 注解
swagger通过注解表明该接口会生成文档,包括接口名、请求方法、参数、返回信息的等等。
@ApiOperation注解来给API增加说明
、通过@ApiImplicitParams、@ApiImplicitParam注解来给参数增加说明
。
@Api:修饰整个类
,描述Controller的作用
@ApiOperation:描述一个类的一个方法
,或者说一个接口
@ApiParam:单个参数
描述
@ApiModel:用对象
来接收参数
@ApiProperty:用对象接收参数时,描述对象的一个字段
@ApiResponse:HTTP响应其中1个描述
@ApiResponses:HTTP响应整体描述
@ApiIgnore:使用该注解忽略这个API
@ApiError :发生错误返回的信息
@ApiImplicitParam:一个请求参数
@ApiImplicitParams:多个请求参数
2.4 实例
@RestController
@Api(tags = "sysArea",description = "病区相关操作")
@RequestMapping(value = "/sysArea")
@CheckException(reason = "检查病区操作参数的合法性")
public class SysAreaController {
@Resource
private SysAreaService sysAreaService;
@ApiOperation(value = "根据id查询病区")
@RequestMapping(value = "/{id}", method = RequestMethod.GET)
@ResponseStatus(HttpStatus.OK)
public SysArea get(@PathVariable int id){
return sysAreaService.get(id);
}
}
3 用到的注解
Spring MVC中
最为常用的几个核心注解:
-
@Controller:
修饰class
,用来创建处理http请求的对象 -
@RestController:Spring4之后加入的注解,原来在@Controller中返回json需要@ResponseBody来配合,如果直接用@RestController替代@Controller就不需要再配置@ResponseBody,默认返回json格式。
-
@RequestMapping:配置url映射
参数绑定的注解
:
- @
PathVariable
- @ModelAttribute
- @RequestParam
- @
RequestBody