JAVA开发环境接口swagger-ui使用总结

一、前言

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.