37

我正在尝试将我的 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"
            }
          }
        }
      }
    }
  }
}

4

8 回答 8

27

您实际上是在一个问题中提出了几个问题，我将尝试全部回答。

在 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）而不是模式，所以在发生冲突的情况下，规范“获胜”。

编辑：

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

于 2014-11-13T20:20:23.407 回答
10

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

于 2015-07-26T20:32:18.397 回答
3

如果 JSON ref 不适合您，编写您自己的连接器可能会很有用。好吧，您实际上可以使用已经存在的东西，而不是自己编写。任何模板引擎都可以。就我而言，Handlebars 非常有用（因为 Handlebars 实际上保留了缩进，这对于 Yaml 文件来说是完美的，因为它们区分大小写）。

然后你可以在 Node 中有一个构建脚本：

'use strict';

var hbs = require('handlebars');
var fs  = require('fs');

var dir = __dirname + '/your_api_dir';

var files = fs.readdirSync(dir);

files.forEach((fileName) => {
  var raw = fs.readFileSync(dir + '/' + fileName, 'utf8');
  hbs.registerPartial(file, raw);
});

var index = fs.readFileSync(dir + '/index.yaml');

var out = hbs.compile(index.toString());

在我的博客上阅读有关该问题的更多信息。

于 2016-02-18T17:53:50.367 回答
2

请注意，RepreZen API Studio$ref现在通过此处讨论的语法支持多文件 Swagger/Open API 项目。因此，您可以将大型 Swagger 项目分解为模块，以实现重用和团队协作。然后，当您需要将 API 模型置于设计/开发环境之外时，您可以使用内置的 Swagger 规范化器来创建单个整合的 Swagger 文件。

注意：为了充分披露，我是 RepreZen 的产品经理。上周我偶然发现了这个线程，并认为我会参与进来。

于 2016-09-30T10:45:45.557 回答
1

我也在尝试解决这个问题，并且在Swagger Google group中有一些有用的信息。看起来共识是，只要 $ref 指向绝对 url，您就可以将定义分成单独的文件。这里的例子：

https://github.com/swagger-api/swagger-spec/blob/master/fixtures/v2.0/json/resources/resourceWithLinkedDefinitions.json#L32

https://github.com/swagger-api/swagger-spec/blob/master/fixtures/v2.0/json/resources/resourceWithLinkedDefinitions_part1.json

于 2015-04-03T04:04:42.097 回答
0

如果json不适合你，你也可以使用node.js，你也可以使用module.exports

我在模块中有我的定义，我可以在模块中要求一个模块：

const params = require(./parameters);
module.exports = {
  description: 'Articles',
  find: {
    description: 'Some description of the method', 
    summary: 'Some summary',
    parameters: [
        params.id,
        params.limit,


...
于 2017-03-22T08:10:26.993 回答
0

我写了一个 Swagger/OpenAPI 预处理器来简化规范的编写。

https://github.com/dolmen-go/openapi-preprocessor/

特别是它支持$ref指向外部文件并允许将您的规范编辑为多个文件，但生成单个文件以最大程度地与将使用它的工具兼容。

于 2018-11-26T14:31:37.857 回答
0

通过为每个模块创建文档集，可以将 Swagger JSON 拆分为多个模块，如下所示：

`

@Bean
public Docket module1() {
      return new Docket(DocumentationType.SWAGGER_2)
        .select()
        .apis(RequestHandlerSelectors.basePackage("com.example.module1"))
        .paths(PathSelectors.any())
        .build()
        .groupName("module1")
        .apiInfo(apiInfo());
}

`

每个模块的 URL 都会像http://localhost:xxxx/context-path/v2/api-docs?group=module1这样创建

于 2020-05-14T08:04:31.457 回答