一 前言
这篇文章主要是带大家入门下如何使用OpenAPI, 笔者在github上找到对应得swagger项目都没找到javase得人门文章，看了下是基于JAX-RS，吐血了；
二 什么是 OpenAPI，
OpenAPI 是 一种基于Resful 风格 对 API进行格式化描述的一种规范； 允许你描述你整个项目的API，简单的讲就是一种接口文档生成的规范；包括如下几点 ：
- 端点描述（如 GET /user , Post /user）;
- 操作的参数，入输入参数，输出参数；
- 认证信息
- 联系信息，许可条款，声明等
三 什么是 Swagger
Swagger 由多个组件组成，它是一个开源的构建工具，其作用就是以 OpenAPI 为 规范基准， 能够帮助开发人员设计，构建文档，测试接口，文档规范化，和消费掉Restful API；说白了就是 OpenAPI 的实现，能够生成接口文档，以后不用自己手写了！！！ 我们可以看下其主要组件如下：
- Swagger Editor 是一个编辑工具，可以编辑描述API；
- Swagger UI 能让OpenAPI呈现出规范的可交互的API文档，以供他人查阅；
- Swagger Codegen 基于OpenAPI规范 能够生成客户端类库，服务端文档和存根，并且支持多语言，支持使用Docker,jar等方式运行构建；
更多组件详细看官网：swagger doc，看了官网的ylm格式基本结构晕，一堆黑的，客户体验非常不友好吐槽一下！看了github是基于JAX-RS 应用 ，不是很懂，再吐槽一下；
四 API生成
4.1 相关注释
| 注释 | 说明 |
|---|---|
| @Api | 标记类上，表明是资源 |
| @ApiImplicitParam | 表示API操作中的单个参数。 |
| @ApiImplicitParams | 允许多个参数列表 |
| @ApiModel | 针对实体model提供额外信息 |
| @ApiModelProperty | 添加操作数据或者model属性 |
| @ApiOperation | 描述HTTP方法，通常针对特定的路径 |
| @ApiParam | 对于操作添加额外的信息 |
| @ApiResponse | 描述一个操作的响应 |
| @ApiResponses | 允许多个参数列表，描述响应对象 |
| @Authorization | 使用在类上或者方法上，表示授权信息 |
| @AuthorizationScope | 描述 OAuth2 的授权作用域 |
| @ResponseHeader | 代表响应头的部分信息 |
4.2 pom.xml
<dependencies>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-annotations</artifactId>
<version>1.5.22</version>
</dependency>
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-models</artifactId>
<version>1.5.22</version>
</dependency>
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
<version>1.16.18</version>
<optional>true</optional>
</dependency>
</dependencies>4.3 swagger配置
主要是配置一些项目得基本信息，注解路径，项目主要联系人等；比较重要是@EnableSwagger2表示开启Swagger；
/**
* @Author lsc
* <p> swagger 配置 </p>
*/
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
// 构建文档
Docket docket = new Docket(DocumentationType.SWAGGER_2);
// 文档信息
Docket build = docket.apiInfo(apiInfo())
// 查询
.select()
// 注解包的路径
.apis(RequestHandlerSelectors.basePackage("com.zszxz.swagger.controller"))
// 任何路径
.paths(PathSelectors.any())
.build();
return build;
}
/* *
* @Author lsc
* <p> 文档信息</p>
* @Param []
* @Return springfox.documentation.service.ApiInfo
*/
private ApiInfo apiInfo() {
// 文档对象构建器
ApiInfoBuilder apiInfoBuilder = new ApiInfoBuilder();
// 文档标题
ApiInfo apiInfo = apiInfoBuilder.title("知识追寻者（公众号） API doc")
// 描述信息
.description("知识追寻者第一次操作OpenAPI！！！！！")
// 版本号
.version("v1")
// 联系人
.contact(new Contact("知识追寻者", "https://blog.csdn.net/youku1327", "[email protected]"))
// 声明许可
.license("知识追寻者许可")
// 许可路径，这边是我的github
.licenseUrl("https://github.com/zszxz")
.build();
return apiInfo;
}
}4.4 实体
/**
* @Author lsc
* <p> </p>
*/
@Data
@ApiModel(description = "用户知识追寻者实体")
public class ZSZXZ {
@ApiModelProperty(value = "姓名",dataType = "String")
private String name;
@ApiModelProperty(value = "邮件",dataType = "String")
private String email;
@ApiModelProperty(value = "爱好",dataType = "String")
private String hobby;
}4.5 controller
/**
* @Author lsc
* <p> </p>
*/
@RestController
// 资源信息
@Api(value = "知识追寻者文档API")
public class SwaggerController {
// 方法注释
@ApiOperation(value = "获取用户")
// 响应信息
@ApiResponse(code = 200,message = "获取用户列表成功")
@GetMapping("zszxz")
public ResponseEntity getUser(){
ZSZXZ zszxz = new ZSZXZ();
zszxz.setName("知识追寻者");
zszxz.setHobby("爱睡觉");
zszxz.setEmail("不告诉你");
return ResponseEntity.ok(zszxz);
}
// 方法注释
@ApiOperation(value = "跟据用户编号获取用户")
// 响应信息
@ApiResponses({@ApiResponse(code = 200,message = "获取用户列表成功")
,@ApiResponse(code = 204,message = "没有内容")})
// 参数信息
@ApiImplicitParam(name = "id", value = "用户编号", dataType = "ZSZXZ",required = true, paramType = "path")
@GetMapping("zszxz/{id}")
public ResponseEntity getUserById(@PathVariable Long id){
ZSZXZ zszxz = new ZSZXZ();
zszxz.setName("知识追寻者");
zszxz.setHobby("爱睡觉");
zszxz.setEmail("不告诉你");
return ResponseEntity.ok(zszxz);
}
@PostMapping("zszxz")
// 响应信息
@ApiResponse(code = 201,message = "添加用户列表成功")
// 方法信息
@ApiOperation(value = "添加用户")
public ResponseEntity addUser(@RequestBody ZSZXZ zszxz){
System.out.println("save the user:"+zszxz);
return ResponseEntity.ok("success save the user");
}
// 响应信息
@ApiResponse(code = 200,message = "修改用户成功")
@ApiOperation(value = "修改用户",notes = "修改用户")
@PutMapping("zszxz/{id}")
// 参数信息 多个参数使用注释中得内容, @RequestBody 修斯参数没必要写
/*@ApiImplicitParams({@ApiImplicitParam(name = "id", value = "用户编号", dataType = "Long",required = true,paramType = "path")
,@ApiImplicitParam(name = "user", value = "用户", dataType = "ZSZXZ",required = true, paramType = "json")})*/
@ApiImplicitParam(name = "id", value = "用户编号", dataType = "Long",required = true,paramType = "path")
public ResponseEntity updateUser(@PathVariable Long id ,@RequestBody ZSZXZ zszxz){
System.out.println("update the user:"+zszxz);
return ResponseEntity.ok("success update the user,the number is :"+id);
}
// 响应信息
@ApiResponses({@ApiResponse(code = 200,message = "删除用户成功")
,@ApiResponse(code = 401,message = "没有权限")
})
@ApiOperation(value = "删除用户")
@DeleteMapping("zszxz/{id}")
@ApiImplicitParam(name = "id", value = "用户编号", dataType = "Long",required = true,paramType = "path")
public ResponseEntity updateUser(@PathVariable Long id ){
System.out.println("delete the user :"+id);
return ResponseEntity.ok("delete the user :"+id);
}
}4.6 生成结果
默认路径：localhost:8080/swagger-ui.html#/
4.7 查看实体
4.8 查询接口测试
打开测试查询接口：
测试结果：
4.9 添加用户测试
由于注解时偷懒没加example，所以这边测试要自己动手写测试数据；
测试结果如下
五 结语
修改和删除就不测试了，很简单，读者自行测试；基本常用得注解使用都过了，其余得读者自行研究，总体来说使用还是很愉快，默认文档路径是可以修改得，读者自行搜索；源码请看作者博客专栏说明；
原文地址：https://www.cnblogs.com/zszxz/p/12195734.html
时间： 2024-09-30 14:28:09