5

質問:ファイル間で Swagger 定義を分割するにはどうすればよいですか? その分野での可能性は何ですか？質問の詳細は次のとおりです。

私が欲しいものの例 - RAMLで

私はRAMLの経験があり、私がしていることは、たとえば次のとおりです。

/settings:
  description: |
    This resource defines application & components configuration
  get:
    is: [ includingCustomHeaders ]
    description: |
      Fetch entire configuration
    responses:
      200:
        body:
          example: !include samples/settings.json
          schema: !include schemas/settings.json

ここで最後の 2 行が重要です - Theones with !include <filepath>- RAML では、コントラクト全体を RAML パーサーによって動的に含まれる多くのファイルに分割できます (RAML パーサーは、RAML に基づくすべてのツールで使用されます)。

これによる私の利点は次のとおりです。

  • スキーマがインライン化されていないため、コントラクトがより明確になり、保守が容易になります
  • しかし、これは非常に重要です。他のツール内でスキーマ ファイルを再利用して、検証、モック生成、スタブ、テストの生成などを行うことができます。つまり、このようにして、コントラクト (RAML、この場合) と他のツール (非 RAML、非スワガー、JSONschema ベースのもののみ) の両方でスキーマ ファイルを再利用できます。

スワガーに戻る

私が読んだ限りでは、swagger は$ref外部ファイルをロードできるキーワードをサポートしています。しかし、そのファイルは HTTP/AJAX を介して取得されたものですか、それとも単なるローカル ファイルでしょうか?

そして、それは仕様全体でサポートされていますか?それとも、それをサポートするツールとサポートしないツールだけですか?

ここで見つけたのは、swagger の入力は 1 つのファイルでなければならないということです。そして、これは大きなプロジェクトにとって非常に不便です:

  • サイズのせいで
  • また、闊歩でないものを使用したい場合、スキーマを再利用できないため

または、言い換えれば、ファイルを分割するという点で、RAMLでできるのと同じことをswaggerで達成できますか?

4

4 に答える 4

6

仕様では、複数の場所での参照が許可されていますが、すべての場所での参照は許可されていません。これらの参照は、仕様がホストされている場所と、何をしようとしているかに応じて解決されます。

動的なユーザー インターフェイスをレンダリングするようなものでは、多くのファイルから構成される可能性のある「単一のオブジェクト」に定義全体を最終的にロードする必要があります。コード生成を実行する場合、定義はファイル システムから直接ロードできます。しかし、最終的には解決を行う Swagger パーサーが存在します。これは、Swagger では他の定義形式よりもはるかにきめ細かく、制御可能です。

あなたの場合、スキーマ参照への JSON ポインターを使用します。

responses:
  200:
    description: the response
    schema:

ローカル参照経由

      $ref: '#/definitions/myModel'

絶対参照経由：

      $ref: 'http://path/to/your/resource'

「このドキュメントがロードされている場所に相対的」な相対参照を介して

      $ref: 'resource.json#/myModel

インライン定義経由

      type: object
      properties:
        id:
          type: string
于 2016-02-22T15:58:33.773 に答える
1

Swagger ドキュメントを多数のファイルに分割する方法の詳細については、この回答を参照してください。これは JSON を使用して行われますが、同じ概念が RAML に適用できます。

編集：ここにリンクのコンテンツを追加

Swagger JSON の基本構造は次のようになります。 

{
"swagger": "2.0",
"info": {
    "title": "",
    "version": "version number here"
},
"basePath": "/",
"host": "host goes here",
"schemes": [
    "http"
],
"produces": [
    "application/json"
],
"paths": {},
"definitions": {}
}

pathsとはdefinitions、API がサポートするパスと、応答オブジェクトを記述するモデル定義を挿入する必要がある場所です。これらのオブジェクトを動的に設定できます。これを行う 1 つの方法は、エンティティのパスとモデルごとに個別のファイルを用意することです。

API のオブジェクトの 1 つが「車」であるとします。

道： 

{
"paths": {
    "/cars": {
        "get": {
            "tags": [
                "Car"
            ],
            "summary": "Get all cars",
            "description": "Returns all of the cars.",             
            "responses": {
                "200": {
                    "description": "An array of cars",
                    "schema": {
                        "type": "array",
                        "items": {
                            "$ref": "#/definitions/car"
                        }
                    }
                },
                "404": {
                    "description": "error fetching cars",
                    "schema": {
                        "$ref": "#/definitions/error"
                    }
                }
            }
        }
    }
}

モデル： 

{
"car": {
    "properties": {
        "_id": {
            "type": "string",
            "description": "car unique identifier"
        },
        "make": {
            "type": "string",
            "description": "Make of the car"
        },
        "model":{
            "type": "string",
            "description": "Model of the car."
        }
    }
}
}

次に、これらをそれぞれ独自のファイルに入れることができます。サーバーを起動すると、これら 2 つの JSON オブジェクトを取得して、基本の swagger オブジェクト ( または のいずれpathsかdefinitions) の適切なオブジェクトに追加し、その基本オブジェクトを Swagger JSON オブジェクトとして提供できます。

サーバーの起動時に一度だけ追加を行うことで、これをさらに最適化することもできます (サーバーの実行中に API ドキュメントは変更されないため)。次に、「serve Swagger docs」エンドポイントがヒットすると、サーバーの起動時に作成したキャッシュされた Swagger JSON オブジェクトを返すことができます。

「serve Swagger docs」エンドポイントは、/api-docs以下のようなリクエストをキャッチすることで傍受できます。

app.get('/api-docs', function(req, res) {
  // return the created Swagger JSON object here
});
于 2016-02-22T16:14:42.863 に答える