如何将 swagger 2.0 JSON 文件分解为多个模块 [英] How to break swagger 2.0 JSON file into multiple modules

问题描述

我正在尝试将我的 API 文档分解为多个可以独立编辑的 JSON 文件.我能找到的所有示例都使用 Swagger 1.2 模式，它有一个api":{} 对象来分解它.2.0 模式中似乎缺少这一点(http://json.schemastore.org/swagger-2.0一>).所定义的只是一个路径"数组，它将所有 API 端点捆绑到该单个数组中.这在 swagger-ui 中的效果是有一个单一的默认"类别，所有东西都被捆绑到其中，我无法告诉将它拆分.

I'm trying to break my API document up into multiple JSON files that can be edited independently. All the examples I've been able to find use the Swagger 1.2 schema which has a "api":{} object for breaking it down. That appears to be missing from the 2.0 schema (http://json.schemastore.org/swagger-2.0). All that defines is a single "paths" array where it bundles all the API endpoints into that single array. The effect of this in the swagger-ui is there is a single "default" category that everything gets bundled into and no way that I can tell to split it up.

TLDR:如何从 swagger 2.0 架构中的路径拆分操作

TLDR: How do you split operations from paths in the swagger 2.0 schema

{
  "swagger": "2.0",
  "info": {
    "description": "My API",
    "version": "1.0.0",
    "title": "My API",
    "termsOfService": "http://www.domain.com",
    "contact": {
      "name": "[e-mail]"
    }
  },
  "basePath": "/",
  "schemes": [
    "http"
  ],
  "paths": {
    "Authorization/LoginAPI": {
      "post": {
        "summary": "Authenticates you to the system and produces a session token that will be used for future calls",
        "description": "",
        "operationId": "LoginAPI",
        "consumes": [
          "application/x-www-form-urlencoded"
        ],
        "produces": [
          "application/json"
        ],
        "parameters": [{
          "in": "formData",
          "name": "UserName",
          "description": "Login Username",
          "required": true,
          "type": "string"

        }, {
          "in": "formData",
          "name": "Password",
          "description": "Password",
          "required": true,
          "type": "string"

        }],
        "responses": {
          "200": {
            "description": "API Response with session ID if login is allowed",
            "schema": {
              "$ref": "#/definitions/Authorization"
            }
          }
        }
      }
    }
  }
}

推荐答案

你实际上将几个问题合而为一，我会尽量一一解答.

You actually ask several questions in one, and I'll try answering them all.

在 Swagger 1.2 及之前的版本中，文件拆分是强制性的和人为的.它是一种对操作进行分组的方式，Swagger 2.0 提供了一种替代方法来做到这一点(稍后会详细介绍).

In Swagger 1.2 and prior to it, the file splitting was mandatory and artificial. It was meant as a way to group operations, and Swagger 2.0 offers and alternative method to do that (more on it soon).

Swagger 2.0 确实是一个单独的文件，它允许在任何使用 $ref 的地方使用外部文件.您不能将单个服务拆分为多个文件并将它们组合为一个文件，但您可以在外部指定特定路径的操作(同样，使用 $ref 属性).

Swagger 2.0 is indeed a single file, which allows for external files wherever $ref is used. You cannot split a single service into several files and combine them as one, but you can specify operations for specific paths externally (again, using the $ref property).

我们目前正在最终确定将多个微服务整理成一个集合的能力，但最终，每个微服务仍将是一个文件.

We're currently in the process of finalizing the ability to collate several micro-services into a single collection, but eventually, each micro-service is still going to be a single file.

如前所述，Swagger 2.0 中的操作分组发生了变化，资源"的概念不再存在.相反，可以为每个操作分配标签(带有 "tags" 属性).tags 是一个值数组，与以前的版本不同，如果需要，每个操作可以存在于多个标签下.在 Swagger-UI 中，所有未定义标签的操作都将在 default 标签下结束，这是您所见过的行为.在顶级对象中有一个额外的 tags 属性，它允许您向标签添加描述并设置它们的顺序，但不是必须包含它.

As mentioned, the grouping of operations in Swagger 2.0 has changed, and the concept of a 'resource' no longer exists. Instead, there are tags (with the "tags" property) which can be assigned per operation. The tags is an array of values, and unlike previous versions, each operation can exist under multiple tags if needed. In Swagger-UI, all operations that have no tags defined will end up under the default tag, which is the behavior you've seen. There's an additional tags property at the top-level object that allows you to add descriptions to tags and set their order, but it is not mandatory to include it.

最后一点，我不知道 Swagger 2.0 的 json-schema 是如何在 http 中结束的://json.schemastore.org/swagger-2.0 但它肯定不是最新的.最新的架构可以在这里找到 - http://swagger.io/v2/schema.json - 它仍在开发中.请记住，事实的来源是规范(https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md) 而不是架构，因此在发生冲突时，规范会胜出".

As a final note, I have no idea how the json-schema of Swagger 2.0 ended up in http://json.schemastore.org/swagger-2.0 but it is certainly not up to date. The most up-to-date schema can be found here - http://swagger.io/v2/schema.json - and it is still under development. Keep in mind that the source of truth is the spec (https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md) and not the schema, so in case of conflicts, the spec 'wins'.

我们刚刚发布了参考指南.它可能对某些用例有所帮助 - https://github.com/OAI/OpenAPI-Specification/blob/master/guidelines/v2.0/REUSE.md

We just published a guide on referencing. It may help with some use cases - https://github.com/OAI/OpenAPI-Specification/blob/master/guidelines/v2.0/REUSE.md

这篇关于如何将 swagger 2.0 JSON 文件分解为多个模块的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！