问题标签 [openapi]

我最近才开始研究 Swagger 2.0 API。我正在寻找一些方法来组织 API 文档。

目前我正在使用@Api(tags = {"Heading1"})Java 注释来标记每个 API。生成的文档看起来像

我想在文档中添加一些副标题，使其看起来像

我如何实现这一目标？

我正在关注标准环境中 App Engine 上 Cloud Endpoints Frameworks 的快速入门。我已经部署了示例 API。当我打开https://[my-project].appspot.com/时，我收到错误消息：

日志显示消息：

app.yaml 处理程序是 endpoints-frameworks-v2/echo 示例附带的：

在快速入门的上一步中，我很难生成 OpenAPI 配置文件。我通过更新 SDK 的系统变量路径让它工作，但我确实收到了这个错误：

我不知道这个错误是否与当前问题有关。

任何帮助将非常感激。

I would like to describe the XML response payload of a RESTful interface with OpenAPI 2.0 (Swagger 2.0). However, I struggle describing a particular XML tag in the OpenAPI data model.

I can't get Swagger UI to create an appropriate example XML tag in this form, with an attribute and content between the opening and closing XML tags:

The documentation (here) only describes how to model a tag with sub tags (type: object) or a tag with content (type: string), but not both at the same time.

I tried this, which the Swagger Editor accepts without any errors or warnings:

but it will be rendered by Swagger UI to the following example:

As you can see, no "foo" content in there.

我参考了几个网站

1. 节点js topclient

2. 淘宝节点包

3. 节点淘宝topclient

我做了什么：

我安装了node-taobao-topclient

我的代码：

当我运行上面的代码时，我得到错误：

TypeError：TopClient 不是构造函数

由于我是节点新手，所以我不知道如何像在参考网站上那样准确地使用这样的包，他们正在使用它，例如：

我的 node-taobao-topclient 包如下所示：

任何有关如何在节点中使用此 API 的指导将不胜感激。

我正在寻找一种优雅的方式来定义一个可以使用 JSON 数据以及表单数据的 api。以下代码段有效，但它并不优雅，并且需要在后端使用各种丑陋的代码。有没有更好的方法来定义这个？

现在有效的方法：

我希望它如何工作的基本想法：

但这不起作用，因为in值必须是字符串，而不是数组。

有什么好主意吗？

我有一个 API 允许传入任意路径，例如所有这些：

• /api/tags
• /api/tags/foo
• /api/tags/foo/bar/baz

是有效的路径。我试图描述如下：

但是，https: //generator.swagger.io 在路径中编码斜杠，所以它不起作用。那么有没有办法在 Swagger 中描述我的 API？

我是 OpenAPI 的新手，我需要一些帮助来为 PayPal 的支付 API创建一个基本的 swagger 文件，以便从我们的平台创建支付。注意：OAuth 已配置。

下面是一个基本的招摇文件，但我不知道在哪里将付款请求信息（即意图、付款人、交易等）添加到：

在 editor.swagger 上测试文件时，我收到有关交易、付款人和意图的“OBJECT_ADDITIONAL_PROPERTIES”错误。

作为我最后一年项目的一部分，我正在使用适用于 Java 的 Cloud Endpoints Frameworks (2.0.1)，并且到目前为止相对成功。部署到我的 appspot.com 域时没有任何问题，但是在本地部署时遇到了一些问题。

（以下代码块中对 my-project-id 的任何引用都是我的实际谷歌云项目 ID 的别名）

我有一个带注释的@API 类的有效openapi 描述符（openapi.json），我正在使用“gcloud service-management deploy openapi.json”将其部署到云端点。命令返回成功：

然后我将返回的 config_id 映射到我的 app.yaml 中的正确 endpoints_api_service

此服务由 gcloud cli 工具使用“gcloud service-management list”列出

和“gcloud service-management configs list --service api.endpoints.my-project-id.cloud.goog”

并且可以在我的 appspot.com 域上访问（我可以调用端点并接收正确的响应）

我正在尝试使用 java 的 maven appengine 插件（mvn appengine:devserver）在 localhost 上部署我的项目，但是在码头启动时，我遇到了以下异常：

然后，部署陷入无休止的循环，尝试启动码头，并被该错误消息击中，然后重新启动等。任何访问 localhost:8080 的尝试都会导致“503：找不到服务”错误

我假设我的应用程序的本地部署能够访问使用“gcloud service-management deploy”部署的服务配置，就像appspot.com 部署一样，但不是这样吗？查看 ServiceConfigSupplier.getchLatestServiceVersion() 的源代码，我收集到 serviceManagement.services().configs().list(my-service-name).execute().getServiceConfigs() 正在返回一个空列表，但为什么这只是发生在本地？

额外的信息

我的 ENDPOINTS_SERVICE_NAME 环境变量匹配“api.endpoints.my-project-id.cloud.goog”

我注意到几天前 com.google.api.config 有一个更新（1.0.2），它依赖于旧版本的 com.google.api.services.servicemanagement（依赖于 v1-rev14 -1.22.0，最新版本是 v1-rev340-1.22.0）我怀疑这是问题所在，但我想我会提到它，因为它包含与异常相关的类（ServiceManagement 由 ServiceConfigSupplier 使用，它正在抛出例外）。也许他们在哪里寻找服务配置不一致？

我很困惑，这有点过头了。我不喜欢必须删除端点，因为我开始喜欢它，但我们也不能真正失去对开发服务器的使用。我希望有人可以对这个问题有所了解。

在 OpenAPI 中，继承是通过allof. 例如，在此示例中：

我在规范中没有找到任何关于多重继承的内容。例如，如果 Pet 继承自 NewPet 和 OldPet。

在 Python 中，我会写

并且方法解析顺序是确定应该首先检查哪个父类的方法/属性，所以我可以判断 Pet.age 是 NewPet.age 还是 OldPet.age。

那么，如果我让 Pet 从 NewPet 和 OldPet 继承，其中 name 属性在两个模式中定义，并且每个模式中的值不同，该怎么办？Pet.name 是什么？

OldPet 会优先吗？新宠物？它未定义/无效？它是应用程序定义的吗？

我在swagger-editor中试过这个。显然，具有两个 refs 的模式是有效的，但 swagger-editor 不解析属性。如果只显示两个引用的 allof。

编辑：根据本教程，在同一个 allof 中有多个 refs 是有效的。但是，对于两个模式具有相同名称的不同属性的情况，什么也没说。

在我的 API 中，我想为我的收藏提供一个简单的模型，并为我的个人资源提供一个更精细的模型。例如：

一个 GET 请求/libraries应该返回

而对特定库的请求应返回上述所有内容，包括额外的参数书：

所以一个 GET 请求libraries/{library_id}应该返回：

我非常希望不必定义“BaseLibrary”两次，并希望简单地建模一个附加的“ExtendedLibrary”，其中包含基础库的所有响应和附加的书籍属性。

我尝试了很多不同的东西，最接近成功的是以下定义：

然而，这给了我一个“额外的 JSON 参考属性将被忽略：书籍”警告，并且输出似乎忽略了这个额外的属性。有没有一种干净的方法来处理我的问题？还是我只需要将整个 BaseLibrary 模型复制粘贴到我的 ExtendedLibrary 模型中？