swagger-parser: Using external file with all definitions doesn't work

We have a file with all the definitions for a given service in a separated file and we need to reuse it in multiple api definitions but we cannnot import it. The definition original definition file use model with nested models etc and we need to import a lot of these, we cannot repeat all the names with all the $refs in every api definition.

In this example we need import all the definitions from _testdrivemulti.yaml and use it in the main api definition but it doesn’t work.

# Testing swagger
swagger: '2.0'
info:
  title: API ejemplo QIS
  description: Un ejemplo de definición para QIS usando swagger
  version: "1.0.0"
host: www.example.com
# array of all schemes that your API supports
schemes:
  - https
# will be prefixed to all paths
basePath: /v1
produces:
  - text/xml
  - application/json
securityDefinitions:
  apiKey:
    type: apiKey
    name: api_key
    in: query
paths:
  /testdrives:
    get:
      summary: Test Drives
      description: Detalle de vehículos
      security:
        - api_key: []
      parameters:
        - name: filtros
          in: body
          description: Body con todos los filtros aplicables
          required: true
          schema:
            $ref: '#/definitions/BusquedaGenerica'
      responses:
        200:
          description: Todo correcto
          schema:
            $ref: '#/definitions/TestDrive'

        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
definitions:
  $ref: './_testdrivemulti.yaml'
  Error:
    properties:
      code:
        type: integer
        format: int32
      message:
        type: string
      fields:
        type: string

Cliente:
  x-dms-file: FMCUCG
  properties:
    nombre:
      type: string
    apellido1:
      type: string
TestDrive:
  x-dms-file: FXTESTDRIVEPT
  properties:
    idv:
      type: integer
      description: Id del vehículo
    cliente:
      type: object
      $ref: '#/definitions/Cliente'

About this issue

  • Original URL
  • State: closed
  • Created 9 years ago
  • Comments: 16 (14 by maintainers)

Commits related to this issue

Most upvoted comments

@diegode That’s a common mistake, but Swagger syntax is not a subset of JSON Schema. The Schema Object, under the Swagger spec is a subset of JSON Schema. The rest of the structure is just a JSON format we chose, and we chose to support JSON References in some places. I won’t go into it here, but there are pros and cons to allowing JSON References everywhere. I agree we should extend the locations, I disagree we should allow them everywhere.

In any case, just because other tools dereference all the references automatically, doesn’t make them right 😉