Swagger 聚焦:生成 OAS、使用 Swagger UI 进行测试等等

本周的《Swagger 聚焦》汇集了来自网络各处的新鲜内容,这些内容由使用 OpenAPI 规范和 Swagger 工具构建 API 的个人撰写。
  2018 年 4 月 30 日

本周的《Swagger 聚焦》汇集了来自网络各处的新鲜内容,这些内容由使用 OpenAPI 规范和 Swagger 工具构建 API 的个人撰写。我们精心挑选了本周的文章,同时也接受下一期《Swagger 聚焦》的投稿,以便在 Swagger 博客上发布。如果您想撰写一篇 Swagger 聚焦专题文章,请在此处查看我们正在寻找的内容并立即提交您的话题。如果您希望围绕您正在进行的项目建立知名度,或者只是分享您对 Swagger 工具的知识,我们都乐意倾听您的声音!

ICYMI – 上周的 Swagger 聚焦专题

使用 Python 自动生成 OpenAPI 规范与文档

在本文中,Thomas Pollet 将引导您了解如何使用他在 GitHub 上的项目,通过 Python 自动生成 OAS 规范Swagger UI 文档。他创建了一个开源的 python-pip 包: safrs。safrs 是主要所用技术的首字母缩写:SqlAlchemy、Flask-Restful 和 Swagger。他讨论了该框架的目的是帮助 Python 开发人员为 SQLAlchemy 数据库对象和关系创建自文档化的 JSON API。


我第一次接触 Swagger 是几年前,当时我需要使用 Nutanix REST API 实现一个系统监控应用程序。我发现它是一种非常便捷的调试和文档化 Web 服务的方式。后来,当被要求为另一个项目提供文档时,我重新使用了 Swagger(现在的 OpenAPI),并实现了其规范。

与当今大多数 Web 服务一样,该项目的 API 端点提供了 CRUD 功能:对数据库后端进行创建、读取、更新、删除操作。规范中需要描述的大部分信息已经隐式编码到应用程序中,因此我决定不手动编写规范,而是利用可用的应用程序语义来生成它。

阅读更多

如何使用 Swagger UI 进行 API 测试

本文将引导读者了解如何使用 Swagger UI 进行 API 测试。文章首先介绍了 Swagger UI 的基础知识、为何它是一个值得使用的出色工具,然后深入讲解了如何使用它测试 API 的教程。对于希望在 Swagger UI 中进行手动测试的人来说非常有用。本教程易于理解且直接明了。您可以按照所用的示例 (http://petstore.swagger.io/v2/swagger.json) 进行操作,或者使用您自己的 URL 进行尝试。


在本文中,我将向您展示如何使用 Swagger UI 进行 API 测试。我们将首先讨论  Swagger UI 是什么以及为何值得使用,然后进入教程部分。

什么是 Swagger?

Swagger(现称为 Linux 基金会旗下的 OpenAPI Initiative)是一个框架,用于通过一种通用语言描述您的 API,这种语言易于开发人员和测试人员阅读和理解,即使他们对源代码的了解较少。您可以将其视为房屋的蓝图。您可以使用任何您喜欢的建筑材料,但不能超出蓝图的参数…… 

阅读更多

使用 Swagger 和 Spring Boot 构建 REST API

在这篇文章中,Nikolaos Georgiou 探讨了如何使用 Swagger 工具和 OAS 通过 Java 和 Spring Boot 构建 REST API。他主要关注如何使用 Swagger Codegen 在 Spring 中构建 API。他强调了透彻了解信息的重要性,并清晰地讲解了如何生成代码。如果您正在寻找有关在 Spring 中生成代码的更多信息,请查阅此文。


在这篇文章中,我将使用 Swagger 通过 Java 和 Spring Boot 构建 REST API。Swagger 是一个 API 框架。它使用基于 YAML 的语言来定义 API,并具有支持多种语言的代码生成器。

工具

Swagger 提供了一个在线编辑器,这对于初学者熟悉该语言和语法很有用。但为了生成代码,在本地拥有代码生成器会很方便。

在编辑器的左侧,您可以看到 YAML 语法。在右侧,是 API 的预览,它会随着您修改 YAML 定义而实时更新……

阅读更多

Schema 优先的 API 设计

本指南向您介绍了 Schema 优先(有时称为设计优先)API 设计背后的策略,以及如何使用 Swagger 工具开始使用 OpenAPI 规范。Yos Riady 非常出色地强调了优先考虑 OpenAPI 规范进行设计的好处。如果您正在权衡使用 OAS 进行设计的优缺点,这是一个非常深入且宝贵的资源。


您正在构建一个 API。

您开发了一个带有几个端点的后端服务并将其部署到生产环境。您发布了多个官方的特定语言 API 客户端以及 API 文档。这一天愉快地结束了。

第二天,API 中添加了一个新功能。您必须

  • 更新服务器实现以支持新功能。
  • 更新所有客户端库(每个受支持的平台和语言一个 SDK)。
  • 更新文档。
  • 以上所有内容必须相互保持一致。
  • 此外,前端团队也会被阻塞,直到您的后端 API 完成。 

您重重地叹了口气。有没有更好的方法来做到这一点呢?……

阅读更多 

分享您的 Swagger

您希望您的作品在 Swagger 博客上得到突出展示吗?《Swagger 聚焦》是我们社区的思想者和创作者与 Swagger 社区其他成员分享的机会。我们一直对人们使用 Swagger 工具构建的项目很感兴趣,并相信应该让这个社区的伟大工作闪耀光芒。

立即提交您的想法!

© . All rights reserved.