web-dev-qa-db-ja.com

Swagger 2.0 JSONファイルを複数のモジュールに分割する方法

APIドキュメントを、個別に編集できる複数のJSONファイルに分割しようとしています。私が見つけたすべての例では、「api」：{}オブジェクトを分解するSwagger 1.2スキーマを使用しています。 2.0スキーマにはないようです（ http://json.schemastore.org/swagger-2. ）。定義するのは、すべての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": "[email protected]"
    }
  },
  "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"
            }
          }
        }
      }
    }
  }
}
swaggerswagger-uiswagger-2.0
35
John P

実際には、いくつかの質問を1つにまとめて、それらすべてに答えてみます。

Swagger 1.2以前では、ファイルの分割は必須で人為的なものでした。これは、操作をグループ化する方法として意図されたものであり、Swagger 2.0はそれを行うための代替方法を提供します（詳細は後ほど説明します）。

Swagger 2.0は実際には単一のファイルであり、$ref 使用されている。 1つのサービスを複数のファイルに分割して1つのファイルに結合することはできませんが、特定のパスの操作を外部で指定できます（ここでも、$refプロパティ）。

現在、いくつかのマイクロサービスを単一のコレクションにまとめる機能を完成させる過程にありますが、最終的には、各マイクロサービスはまだ単一のファイルになります。

前述のように、Swagger 2.0の操作のグループ化が変更され、「リソース」の概念はなくなりました。代わりに、タグがあります（"tags"プロパティ）操作ごとに割り当てることができます。 tagsは値の配列であり、以前のバージョンとは異なり、各操作は必要に応じて複数のタグの下に存在できます。 Swagger-UIでは、タグが定義されていないすべての操作はdefaultタグの下に配置されます。これは、これまで見てきた動作です。最上位オブジェクトには、タグに説明を追加して順序を設定できる追加のtagsプロパティがありますが、含めることは必須ではありません。

最後のメモとして、Swagger 2.0のjson-schemaが http://json.schemastore.org/swagger-2. にどのようになったかはわかりませんが、確かに最新ではありません。最新のスキーマはここにあります- 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

27
Ron

これについて このブログ記事 で書いています。基本的にJSON Refsライブラリを使用して、すべての小さなSwaggerファイルを1つの大きなファイルに解決し、ツールで使用できます。

10
Mohsen

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

問題に関する詳細をお読みください 私のブログで 。

2
Oleg Berman

RepreZen API Studio は、ここで説明した$ref構文を介してマルチファイルSwagger/Open APIプロジェクトをサポートするようになりました。そのため、大規模なSwaggerプロジェクトをモジュールに分割して、再利用とチームコラボレーションを実現できます。 APIモデルを設計/開発環境以外で使用する必要がある場合は、組み込みのSwaggerノーマライザーを使用して、単一の統合Swaggerファイルを作成できます。

注：完全な開示のために、私はRepreZenのプロダクトマネージャーです。私は先週このスレッドを偶然見つけて、私はチップを入れると思いました。

2
daffinm

仕様のオーサリングを容易にするためにSwagger/OpenAPIプリプロセッサーを作成しました。

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

特に、$ref外部ファイルをポイントし、仕様を複数のファイルとして編集できますが、それを使用するツールとの互換性を最大限にするために単一のファイルを作成します。

1
dolmen

私もこれを理解しようとしていますが、 Swagger Googleグループ にいくつかの有用な情報があります。コンセンサスは、$ 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

1
Bailey Smith

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,


...
0
Samuel