Defining swagger splitting in many files

Question

Question: how can I split swagger definition between files? What are the opportunities in this area? Details of the question are described below:

an example of what I want is in RAML

I have experience in RAML and what I do, for example:

/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

The last two lines - theones with !include <filepath>- in RAML are important here. I can split my entire contract into many files that are simply included dynamically using the RAML parser (and the RAML parser is used by all tools that are based on RAML).

My advantage is that:

• I get my contract more understandable and easier to maintain, because the schemes are not built-in
• : , , , , ... , (RAML, ), (-RAML, -swagger, JSONschema).

Swagger

, swagger $ref, . , HTTP/AJAX, ?

, , - ?

, , , swagger . :

• -
• , , - -swagger

, , swagger, RAML - ?

Answer 1

, . , , .

- , , " ", . . , , - , 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

Answer 2

. , Swagger . JSON, RAML.

EDIT:

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, , . . .

, API - "".

:

{
"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."
        }
    }
}
}

. , JSON swagger ( paths definitions), Swagger JSON.

, ( API ). , " Swagger docs", Swagger JSON, .

" Swagger docs" /api-docs, :

app.get('/api-docs', function(req, res) {
  // return the created Swagger JSON object here
});

Answer 3

You can use $ ref, but not have good flexibility, I suggest you handle YAML with an external tool such as "Yamlinc", which combines several files into one using the "$ include" tag.

more details: https://github.com/javanile/yamlinc