如何将swagger 2.0 JSON文件分解为多个模块

Question

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

TLDR:如何从swagger 2.0模式中的路径中拆分操作

{
  "swagger": "2.0",
  "info": {
    "description": "My API",
    "version": "1.0.0",
    "title": "My API",
    "termsOfService": "http://www.domain.com",
    "contact": {
      "name": "support@domain.com"
    }
  },
  "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"
            }
          }
        }
      }
    }
  }
}

Answer 1

你实际上在一个问题中提出几个问题,我会尝试全部回答.

在Swagger 1.2及之前,文件拆分是强制性的和人为的.它被用作分组操作的一种方式,Swagger 2.0提供了替代方法(很快就会有更多内容).

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

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

如前所述,Swagger 2.0中的操作分组已经改变,"资源"的概念已不复存在.相反,有"tags"每个操作可以分配的标签(具有属性).这tags是一个值数组,与以前的版本不同,如果需要,每个操作都可以存在于多个标记下.在Swagger-UI中,所有未定义标签的操作都将在default标签下结束,这就是您所看到的行为.tags顶级对象还有一个附加属性,允许您向标记添加描述并设置其顺序,但并不强制包含它.

作为最后一点,我不知道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),而不是模式,所以如果发生冲突, spec'胜'.

编辑:

我们刚刚发布了一个引用指南.它可能有助于一些用例 - https://github.com/OAI/OpenAPI-Specification/blob/master/guidelines/v2.0/REUSE.md

Answer 2

我在这篇博文中写过这篇文章.您基本上可以使用JSON Refs库将所有小Swagger文件解析为一个大文件并在工具中使用它.