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 {

	@Autowired
	private 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.

本图文内容来源于网友网络收集整理提供,作为学习参考使用,版权属于原作者。
THE END
分享
二维码
< <上一篇
下一篇>>