【锁定直播】字节、华为云、阿里云等技术专家讨论如何将大模型接入 AIOps 解决实际问题,戳>>> 了解详情
写点什么

设计你的第一个 REST API:第二部分

  • 2019-11-11
  • 本文字数:2776 字

    阅读完需:约 9 分钟

设计你的第一个 REST API:第二部分

在上一篇文章——《设计你的第一个 REST:第一部分》,作者已经介绍了 REST API 的基本概念。

本文是 REST API 指南的第二部分,本文将重点介绍如何使用 SwaggerHub 设计一个简单的 API 。并解释 SwaggerHub 编辑器和开放 API 规范(Open API Specification)的基本功能。



这是我的 REST API 指南的第二部分,本文将重点介绍如何使用 SwaggerHub 设计一个简单的 API 。还将解释 SwaggerHub 编辑器和开放 API 规范(Open API Specification)的基本功能。我在上一篇文章中已经介绍了 REST API 的基本概念。

介绍

OpenAPI

OpenAPI 是一种编写 API 定义的格式,用于向人们和机器描述 API 的结构。OpenAPI 文件允许我们描述整个 API ,包括:


  • 可用端点以及每个端点上的操作

  • 每个操作的输入和输出参数

  • 身份验证方法

  • 联系信息、许可证、使用条款和其他信息


OpenAPI 规范 2.0 相关信息可以在这里找到。

Swagger

Swagger 是一组基于 OpenAPI 规范构建的开源工具,他可以帮助我们设计、构建、记录和使用 REST APIs。主要的 Swagger 工具包括:


  • Swagger Editor:基于浏览器的编辑器,我们可以在其中编写 OpenAPI 规范

  • Swagger UI :将 OpenAPI 规范渲染成交互式 API 文档

  • Swagger Codegen:根据 OpenAPI 规范生成服务端存根和客户端库


在我看来,使用 Swagger 设计 API 的主要优势在于能够生成交互式和自描述性文档。另一方面,我们可以使用相同的 Swagger 定义为超过 40 种不同的编程语言生成服务端和客户端存根。

开始使用 SwaggerHub

实际上,Swagger Editor 是官方免费的 UI 编辑器,可用于编写 Swagger 定义。SwaggerHub 是一个扩展的商业版编辑器,它能支持更多的特性,比如 goto 定义和协作。因为它们允许我们在 SwaggerHub 中创建免费帐户,所以我们可以使用它而不是 Swagger 编辑器。



首先,最重要的事情。如果我们还没有账户,可以这里创建一个免费帐户。登录后,我们将看到如下所示的界面。单击 Create New ->Create New API 开始设计我们的第一个 REST API 吧。


选择 Simple API 作为模板,为 API 提供一个名称(BookStore),然后单击 **Create API 按钮。它将创建一个新的 swagger 定义,该定义带有一个名为 Simple Inventory API **的示例 API。


Swagger 的基本元素

让我们看下,一个 swagger 定义中包含哪些基本元素。




在文件的顶部,我们可以看到版本;它是 2.0 或 3.0,这是最新版本。


然后,我们看到一个名为 info 的块,它包含了 API 的基本信息,如 API 的名称、描述、版本等。


下一个元素是 paths。这些是 API 中的 URL 路径。每个路径可以有一个或多个操作。在这个简单的库存 API 中,只有一个名为 /inventory 的路径存在,并且该路径有两个操作,即 GETPOST


下一个元素是 definitions,我们可以在这里定义可重用的组件并可以在路径中引用它们。


在 Swagger 中还有其他少数几个元素:


  • host:定义 API 的主机名

  • basePath :定义应该出现在定义路径之前的任何基路径

  • schemes:可以是 http、https、ws、wss 这些值

书店 API 定义

我们先从定义自己的 API 开始。我在上一篇文章中添加了 API 的框架。首先,将下面的内容粘贴到 swagger 编辑器中,开始定义。


swagger: '2.0'info:    title: Book Store API    description: This is an API for an online bookstore    version: v1paths:    /books:        get:        post:    /books/{book-id}:        get:        put:        delete:    /books/{book-id}/reviews:        get:        post:    /books/{book-id}/reviews/{review-id}:        put:        delete:definitions:    # Added by API Auto Mocking Plugin    host: mybookstore.com    basePath: /api/v1    schemes:        - https
复制代码


暂时先不要在意这些错误。我们很快就能将其修好。当我们将上述内容添加到编辑器中时,UI 应该如下所示,其中包含我们的书店 API 路径。



由于我们的 API 有两种资源:书籍和评论,所以我们需要在 swagger 中定义这两个对象。


definitions:    Book:        type: object        required:            - id            - name            - author            - price            - reviews        properties:            id:                type: string                example: B10001                description: Unique id of the book.            name:                type: string                example: The Adventures of Tom Sawyer                description: Name of the book.            author:                type: string                example: Mark Twain                description: Author of the book.            price:                type: string                example: $4.90                description: Price of the book.            reviews:                type: array                description: Reviews of the book.                items:                    $ref: '#/definitions/Review'    Review:        type: object        required:            - id            - score            - comment            - reviwer        properties:            id:                type: string                example: R1001234                description: Unique id of the review.            score:                type: string                example: 4.3                description: Review score.            comment:                type: string                example: Good book to read.                description: Review comment.            reviwer:                type: string                example: vihanga                description: Reviewer.
复制代码


单个书籍元素包含多个评论。注意我们如何在 book 对象中引用 Review 对象。将上述部分添加到 swagger 定义的末尾,并编辑路径**/books/{book id}** 的 GET 请求。


/books/{book-id}:    get:        summary: Retrieve the book resource indentified by the book-id.        operationId: getBook        description: Retrieve the book resource indentified by the book-id.        responses:            200:                description: Search results matching the given criteria.                schema:                $ref: '#/definitions/Book'
复制代码


现在, UI 将重新生成,我们可以展开**GET /books/{book id} **并看到如下所示的示例响应。



现在我们对这项任务已经有了基本的了解。您可以在 SwaggerHub 上找到这个书店的完整 swagger 定义;可以在这里找到 YAML 文件。仔细研究一下,试着自己开发一个新的吧。


希望本文对您有所帮助。


原文链接:


Designing Your First REST API – Part 2


2019-11-11 11:145306

评论

发布
暂无评论
发现更多内容

AI运动:阿里体育端智能最佳实践

阿里巴巴终端技术

最佳实践 端智能

云小课 | 网站接入WAF失败怎么办?看这里就够了

华为云开发者联盟

华为云 Web应用防火墙 接入WAF失败 故障排查

技术分享| 如何做一款容纳百人的视频会议?

anyRTC开发者

音视频 WebRTC 视频会议 实时通信 视频通话

构建 Snowpack + React + Typescript + Electron的Desktop App

DisonTangor

typescript Electron React webpack

一图看懂 Apache ShardingSphere 5.0.0

SphereEx

数据库 开源 ShardingSphere

这可能是,Flutter 中最“强悍”的内存泄漏检测方案......

阿里巴巴终端技术

flutter ios android 内存泄漏

巅峰对话在线研讨 Q&A:Oracle Database 21c vs openGauss 2.0新特性解读和架构演进

墨天轮

数据库 oracle opengauss

博文推荐 | 一文带你看懂 Pulsar 的消息保留和过期策略

Apache Pulsar

架构 云原生 中间件 干货 Apache Pulsar

Kafka中的数据不丢失机制及CAP理论详解

五分钟学大数据

11月日更

亿磐获评《新闻周刊》2021年度最受雇员喜爱工作场所

InfoQ_434670063458

亿磐 EPAM 新闻周刊

APP上运行小程序的混合移动研发模式

Speedoooo

容器 ios开发 APP开发

译文|选择 Apache Pulsar 而非 Kafka 的 10 个理由

Apache Pulsar

kafka 架构 云原生 中间件 Apache Pulsar

频繁更新主机,导致pod ip不够解决方法

ilinux

北省廊坊市本地有等保测评机构吗?在哪里?

行云管家

网络安全 等保 等级保护 等保测评 廊坊

🏆【Alibaba中间件技术系列】「RocketMQ技术专题」小白专区之领略一下RocketMQ基础之最!

洛神灬殇

RocketMQ 消息队列 Alibaba技术 11月日更

Black Hat Europe 2021议题解读:Wi-Fi Mesh中的安全攻击面

百度安全

Black Hat Wi-Fi Mesh

一个站点不够学?那就在用Python增加一个采集目标,一派话题广场+某金融论坛话题广场爬虫

梦想橡皮擦

11月日更

多变的智能降噪

睿象云

运维 告警 智能运维 告警管理

containerd镜像层过大问题

ilinux

ETL和数据建模

大数据技术指南

11月日更

博文推荐|Pulsar 存储空间不释放的问题分析与解决方法

Apache Pulsar

架构 云原生 Apache Pulsar 技术干货 BookKeeper 存储空间

She Builds Summit|邀您一同感受她的科技力量!

SphereEx

开源 AWS SphereEx 潘娟

论文解读丨无监督视觉表征学习的动量对比

华为云开发者联盟

视觉 无监督学习 无监督视觉 表征学习 动量对比

虚拟机与容器的混合管理实践

安第斯智能云

Kubernetes 后端 云化底层的那些事

Python 中的反转字符串:reversed()、切片等

华为云开发者联盟

Python 切片 反转字符串 reversed 反转

TDengine助力曲靖卷烟厂有效提升时序数据存取效率

TDengine

数据库 tdengine 后端

拒绝编译等待 - 动态研发模式 ARK

字节跳动终端技术

ios 字节跳动 移动开发

Go iota 原理和源码剖析

编程宝库

视野 | OpenSearch,云厂商的新选择?

RadonDB

数据库 搜索引擎; Elastic Search

潜藏在手机中的新威胁:免安装应用安全指北

安第斯智能云

安全 移动端

【堡垒机小知识】堡垒机是硬件还是软件?

行云管家

网络安全 信息安全 数据安全 堡垒机

设计你的第一个 REST API:第二部分_文化 & 方法_Vihanga Liyanage_InfoQ精选文章