一、前言
swagger-ui是java开发中生产api说明文档的插件,这是后端工程师和前端工程师联调接口的桥梁。生成的文档就减少了很多没必要的沟通提高开发和测试效率。
二、 swagger-ui的使用
1、引入maven依赖
<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>${swagger2.version}</version></dependency><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>${swagger2.version}</version></dependency>
版本: <swagger2.version>2.9.2</swagger2.version>
2、在springboot启动类上加上注解
@EnableSwagger2
表示开启文档
3、在controller的方法加上注解 @ApiOperation
如:
@RestController
@RequestMapping("tmpMUser")
public class TmpMUserController {@Autowiredprivate TmpMUserService tmpMUserService;@ApiOperation(value = "解密酒店手机号", httpMethod = "POST", response = ResponseData.class, notes = "解密酒店手机号")@PostMapping("updateOne")public ResponseData<String> updateOne(Map<String, Object> param) {try {tmpMUserService.updateOne();return ResponseData.success("成功");} catch (Exception e) {e.printStackTrace();}return ResponseData.error();}}
4、通过项目ip加端口加上swagger-ui.html#访问
http://ip:port/swagger-ui.html#
5、文档说明
文档介绍了接口的请求方式,地址和用途。
三、更加丰富的注解
除了上面简单的使用,api还有很多丰富的注解
/**@Api:修饰整个类,描述Controller的作用@ApiOperation:描述一个类的一个方法,或者说一个接口@ApiParam:单个参数描述@ApiModel:用对象来接收参数@ApiProperty:用对象接收参数时,描述对象的一个字段@ApiResponse:HTTP响应其中1个描述@ApiResponses:HTTP响应整体描述@ApiIgnore:使用该注解忽略这个API@ApiError :发生错误返回的信息@ApiImplicitParam:一个请求参数@ApiImplicitParams:多个请求参数*/
如示例:
@ResponseBody
@PostMapping(value="/login")
@ApiOperation(value = "登录检测", notes="根据用户名、密码判断该用户是否存在")
public UserModel login(@ApiParam(name = "name", value = "用户名", required = false) @RequestParam(value = "name", required = false) String account,@ApiParam(name = "pass", value = "密码", required = false) @RequestParam(value = "pass", required = false) String password){}//或以实体类为参数:
@ResponseBody
@PostMapping(value="/login")
@ApiOperation(value = "登录检测", notes="根据用户名、密码判断该用户是否存在")
public UserModel login(@ApiParam(name = "model", value = "用户信息Model") UserModel model){}
四、swagger-ui介绍
OpenAPI是一个编写API文档的规范,然而如果手动去编写OpenAPI规范的文档,是非常麻烦的。而Swagger就是一个实现了OpenAPI规范的工具集。
Simplify API development for users, teams, and enterprises with the Swagger open source and professional toolset. Find out how Swagger can help you design and document your APIs at scale.