OpenAPI Specification 快速入门(二)

前言

上一节介绍了OpenAPI Specification的概念和必要的组成部分,这节我们来学习API Endpoints[1]这一概念。

由于微信不能插入外链,为了更好的阅读体验,你可以在文章最下方点击”阅读原文“来跳转到我的blog中浏览。

什么是Endpoints?

我们之前说过,OAS就是一份接口文档,每个Endpoints可以理解为一个接口,在path路径下可以有许多的Endpoints,整个OAS几乎都是围绕着Endpoints这一概念来展开的。

从一个例子开始

openapi: 3.1.0 
info:
  title: Tic Tac Toe
  description: |
    This API allows writing down marks on a Tic Tac Toe board
    and requesting the state of the board or of individual squares.
  version: 1.0.0
paths:    # Path Object
  /board: # Path Item Object
    ...
  /foo:   # Path Item Object
    ...
  /bar:   # Path Item Object
    ...

我们来看一下上面这份示例文档,其中openapi,infopath字段我们在上一节已经讲过,值得注意的是,info字段下增添了description字段,用来描述整个文档。而path下也新增了三个接口,/board,/foo,bar这三个就是本节要介绍的Endpoint。
例如:我们的域名为example.com,那么这个文档就描述了example.com/board,example.com/fooexample.com/bar这三个接口。

注:在yaml文件中,#后面的内容为注释

Path Item Object

通过上文我们知道,path字段下可以定义许多Endpoint,每个Endpoint又叫做Path Item Object,而每个Endpoint又可以定义不同的HTTP Method,叫做Operation Object

示例:

paths:
  /board: # Path Item Object
    get:  # Operation Object 
      ...
    put:  # Operation Object
      ..

Operation Object

Path Item Object的基础上,我们又扩充了Operation Object

示例:

paths: # Path Object
  /board: # Path Item Object
    get:  # Operation Object
      summary: Get the whole board
      description: Retrieves the current state of the board and the winner.
      parameters:
        ...
      responses: # Responses Object
        ...

Operation Object对于接口进行了更加详细的补充和说明,每个Path Item Object可以分为许多Operation Object,你可以定义同一个接口针对不同HTTP请求头的不同行为。
可以看到,Operation Obejct包括对HTTP Method的概要、描述、参数和响应的介绍。

Responses Object

paths: 
  /board:
    get: # Operation Object
      responses: # Responses Object
        "200": # response status code
          description: Everything went fine.
          content:  
            ...

顾名思义,Responses Object描述的就是响应的内容,包括状态码等内容,这部分内容展开太长,我们将在以后的内容中介绍。

通过实例学习

上面几部分的内容都是对OAS中的对象进行解释,尽管给出了示例,但没有一点经验的读者依然可能会觉得一头雾水,难以理解,下面我们给出一份使用“到目前为止”所学的所有知识而组成的例子吧,我会一行一行带你理解每个字段。

openapi: 3.1.0
info:
  title: Tic Tac Toe
  description: |
    This API allows writing down marks on a Tic Tac Toe board
    and requesting the state of the board or of individual squares.
  version: 1.0.0
paths:
  # Whole board operations
  /board:
    get:
      summary: Get the whole board
      description: Retrieves the current state of the board and the winner.
      responses:
        "200":
          description: "OK"
          content:
            ...

这个文件叫做tictactoe.yaml,第一行的openapi: 3.1.0说明这个文件使用的是OAS 3.1.0来书写的。如果你学过Python,这行的作用就相当于说明这个文件是使用python2还是使用python3语法进行书写的(众所周知,python2和3的语法是不兼容的)。

第二行的info则对文档进行了概括,包括文档的标题(info下的title字段),文档的总体描述(info下的description字段),而第7行的version则说明了这份文档的版本。

接下来的path字段定义了一个/board接口,并且文档详细描述了,当我们使用get方法访问这个接口时,可能产生的响应以及响应的内容格式(content字段)。

细心观察你会发现,大部分字段里都有description字段,它用于描述对应的字段,在使用工具将文档生成为代码或者接口文档时,这些描述可能会变为对应的注释或者文档上的说明文字。关于tictactoe.yaml的完整代码可以在这里[2]找到.

总结

这一讲我们介绍了如何定义Endpoints以及它的基本属性。关于这些对象完整的属性列表你可以在这里[3]找到。下一讲我们将具体介绍content字段。

往期阅读

我是赵不贪,欢迎关注我的微信公众号:阿贪爱学习

OpenAPI Specification 快速入门(二)


参考资料

[1]

API Endpoints: 笔者水平有限,想来想去,这个单词还是没有翻译,保持原样,不过相信通过文章上下文,你能理解这个单词的意思以及我为什么这样做

[2]

tictactoe.yaml: https://oai.github.io/Documentation/examples/tictactoe.yaml

[3]

OpenAPI Specification: https://spec.openapis.org/oas/v3.1.0


原文始发于微信公众号(梦真日记):OpenAPI Specification 快速入门(二)

版权声明:本文内容由互联网用户自发贡献,该文观点仅代表作者本人。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如发现本站有涉嫌侵权/违法违规的内容, 请发送邮件至 举报,一经查实,本站将立刻删除。

文章由极客之音整理,本文链接:https://www.bmabk.com/index.php/post/167878.html

(0)
小半的头像小半

相关推荐

发表回复

登录后才能评论
极客之音——专业性很强的中文编程技术网站,欢迎收藏到浏览器,订阅我们!