API 入门 (27) 使用 OpenAPI 描述 REST API——资源和操作

Posted 2023-05-07

参考技术A 可以说，在前面的几篇文章中，我们已经对自行车在线商城的 REST API 进行了详细的设计（通过图和表格）。从今天开始，我们要使用 Open API 规范，对已有的 REST API 设计进行描述，朝着最终的开发实现，再迈进一步。

如果想了解和回顾 Open API 的基础知识，可以参考下面的文章：

如果想了解 Open API 环境的搭建，请参考下面的文章：

本文先对 REST API 的资源和操作进行描述。

首先，我们创建一个空白的 Open API 文档，并修改自动产生的标题详细。

接下来，我们以目录资源为例，对资源和操作进行描述。

在 REST API 的设计中，我们已经识别出目录资源，并用 /bikes 表示资源的路径。现在通过文档进行描述。

在 YAML 格式中，可以使用 # 添加注释，这也是 YAML 优于 JSON 的一个地方。

# 1， paths ：表示资源的集合，所有资源都要放到这里。
# 2， /bikes ：表示目录资源的路径。
# 3， description ：对资源的额外描述。不强制，但推荐，很有用。

在 Open API 文档中，资源必须包含相应的操作，否则文档是无效的。现在我们来添加查询操作。

# 1， get ：get 属性对应的是 HTTP 的 GET 方法。
# 2， summary ：表示操作的简短描述。
# 3， description ：表示对操作的详细描述。

还记得 | 这个符号吗？在 这里 可以找到答案。

这时候，文档会提示一个警告： Missing property "responses". 。我们必须需要为操作添加一个响应，满足文档的有效性。

我们添加了一个 responses 属性，表示响应的集合，包含操作所有可能的响应。我们也添加了一个 "200" 响应，表示 HTTP 对状态码，意思是操作成功。最后， description 属性对响应对内容进行了说明。

响应具体包含了哪些数据，我们在后面对文章中进行详细说明。

是不是把设计转换成语言描述很简单？这说明我们对设计工作发挥了作用，让接下来的工作水到渠成。等一等，还缺一个添加操作，请你动手写出来吧。

springboot-使用OpenAPI之后我再也没有写过接口文档

一 前言

这篇文章主要是带大家入门下如何使用OpenAPI, 笔者在github上找到对应得swagger项目都没找到javase得人门文章，看了下是基于JAX-RS，吐血了；

二 什么是 OpenAPI，

OpenAPI 是 一种基于Resful 风格 对 API进行格式化描述的一种规范； 允许你描述你整个项目的API，简单的讲就是一种接口文档生成的规范；包括如下几点 ：

1. 端点描述（如 GET /user , Post /user）;
2. 操作的参数，入输入参数，输出参数；
3. 认证信息
4. 联系信息，许可条款，声明等

OpenAPI 3.0 Specification

三 什么是 Swagger

Swagger 由多个组件组成，它是一个开源的构建工具，其作用就是以 OpenAPI 为 规范基准， 能够帮助开发人员设计，构建文档，测试接口，文档规范化，和消费掉Restful API；说白了就是 OpenAPI 的实现，能够生成接口文档，以后不用自己手写了！！！ 我们可以看下其主要组件如下：

1. Swagger Editor 是一个编辑工具，可以编辑描述API；
2. Swagger UI 能让OpenAPI呈现出规范的可交互的API文档，以供他人查阅；
3. 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", "[e-mail]"))
                // 声明许可
                .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，所以这边测试要自己动手写测试数据；

测试结果如下

五 结语

修改和删除就不测试了，很简单，读者自行测试；基本常用得注解使用都过了，其余得读者自行研究，总体来说使用还是很愉快，默认文档路径是可以修改得，读者自行搜索；源码请看作者博客专栏说明；