如何將Swagger 2.0 JSON文件分解成多個模塊

Question

我想將我的API文檔分解成多個可以獨立編輯的JSON文件。我所能找到的所有示例都使用Swagger 1.2模式，該模式具有「api」：{}對象來分解它。這似乎從2.0架構中缺少（http://json.schemastore.org/swagger-2.0）。所有定義的都是單個「路徑」數組，它將所有API端點捆綁到單個數組中。這在swagger-ui中的效果是有一個單一的「默認」類別，所有東西都被捆綁到了一起，而我沒有辦法將其分解。

TLDR：你如何招搖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模式如何在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

Answer 2

我想弄清楚這一點，以及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

Answer 3

我在this blog post寫這個。您基本上可以使用JSON Refs庫將所有小型Swagger文件解析爲一個大的文件並將其用於工具中。

Answer 4

如果JSON ref不適合你，那麼編寫你自己的連接器可能會很有用。那麼，而不是寫你自己的，你可以使用已經存在的東西。任何模板引擎都可以。在我看來，Handlebars非常有用（因爲Handlebars實際上保​​留了縮進，這對於Yaml文件來說是完美的，因爲它們區分大小寫）。

然後你就可以在節點有一個構建腳本：

'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()); 

瞭解更多關於這個問題on my blog。

Answer 5

請注意，RepreZen API Studio現在通過此處討論的$ref語法支持多文件Swagger/Open API項目。因此，您可以將大型Swagger項目分解爲模塊以實現重用和團隊協作。然後，您可以使用內置的Swagger規範化器創建單個統一的Swagger文件，以便在需要將API模型超出設計/開發環境時使用。

注意：爲了充分披露，我是RepreZen的產品經理。上週我碰到這個線程迷迷糊糊，以爲我會在湊錢。

Answer 6

如果你二，你也可以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, 


...