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

墨蓝 2024-03-24 19:42 136阅读 0赞

#### 一、前言 ####

swagger-ui是java开发中生产api说明文档的插件，这是后端工程师和前端工程师联调接口的桥梁。生成的文档就减少了很多没必要的沟通提高开发和测试效率。

![3ff29d32446946fe929f2b62f92f34cb.png][]

#### 二、 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

表示开启文档

![6a7d243fe2234b4b9e9b27caf6b3d68d.png][]

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\#][http_ip_port_swagger-ui.html]

5、文档说明

![807f385ebafa481dacb9b7c0d2e19cb3.png][]

文档介绍了接口的请求方式，地址和用途。

#### 三、更加丰富的注解 ####

除了上面简单的使用，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介绍 ####

![fca7703d080745178d9e5f31ff35c59c.png][]

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.

[3ff29d32446946fe929f2b62f92f34cb.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/13/ccac4e8690a8485aabbb19fec22a089c.png
[6a7d243fe2234b4b9e9b27caf6b3d68d.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/13/68e1f5f9d5664cc4b90771d001e48334.png
[http_ip_port_swagger-ui.html]: http://10.8.215.8:8305/swagger-ui.html#
[807f385ebafa481dacb9b7c0d2e19cb3.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/13/0b79b98520df4c8bb463df1ab8306db0.png
[fca7703d080745178d9e5f31ff35c59c.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/13/2fb56427154d4cfe9fdbb54a66ce3733.png