Swagger reference to definitions in externalFile

Question

I have many swagger files, using the same definitions. I want to move this definitions to a separate file and reference them.

Main swagger file looks like:

swagger: '2.0'
info:
  version: 1.0.0
basePath: /api
tags:
  - name: MyClient
schemes:
  - http
consumes:
  - application/json
produces:
  - application/json
paths:
  /v1/myrequest:
    post:
      tags:
        - PassportCheck
      summary: Проверить паспорт ФЛ
      operationId: passportCheck
      produces:
        - application/json
      parameters:
        - name: Body
          in: body
          required: true
          description: ''
          schema:
            $ref: '#/definitions/MyRequest'
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/MyResponse'
        '400':
          description: Bad request
          schema:
            $ref: '#/definitions/Errors'

definitions: 
  MyRequest:
    type: object
    properties:
      some properties

File I'm trying to import is saved to exceptions.yaml (and saved to the same location) and looks like:

swagger: '2.0'
info:
  version: 1.0.0
  title: Exception API
tags:
  - name: ExceptionAPI
definitions:
  Errors:
    required:
      - errors
    properties:
      errors:
        type: array
        items:
          data declarations go here

I've read $ref https://swagger.io/docs/specification/using-ref/ but couldn't find how to import definition, instead of an API

I'm trying to import it with following changes:

    '400':
      description: Bad request
      schema:
        $ref: 'exceptions.yaml#/definitions/Errors'

[ERROR] /C:/Data/MyService/target/generated-sources/src/main/java/myservice/rest/v1/api/V1Api.java:[55,70] cannot find symbol
  symbol:   class ExceptionsYamldefinitionsErrors

Or use relative path in different variations

    '400':
      description: Bad request
      schema:
        $ref: '..exceptions.yaml#/definitions/Errors'


[ERROR] Failed to execute goal io.swagger:swagger-codegen-maven-plugin:2.3.1:generate (correqts-adapter) on project individual-client-service: Execution correqts-adapter of goal io.swagger:swagger-codegen-maven-plugin:2.3.1:generate fail
ed: Unable to load RELATIVE ref: ..exceptions.yaml: Could not find ..exceptions.yaml on the classpath ->

or inserting $ref under existing declarations:

definitions:
   $ref: 'exceptions.yaml'  

which was ignored completly

Has anyone solved a similar problem?

Answer 1

This worked for my files. I ensured that the swagger.yaml and definitions.yaml where in the same directory.

src/main/swagger/swagger.yaml

swagger: '2.0'
info:
  title: Stack Overflow
  version: "1.0.0"
# the domain of the service
host: com.stackoverflow
# array of all schemes that your API supports
schemes:
  - https
# will be prefixed to all paths
basePath: /question
consumes:
  - application/json
produces:
  - application/json
paths:
  /hello:
    get:
      operationId: getHelloWorlds
      produces:
        - application/json
      responses:
        200:
          schema:
            type: array
            items:
              $ref: 'definitions.yaml#/definitions/HelloWorldObject'

src/main/swagger/definitions.yaml

swagger: '2.0'
info:
  title: Stack Overflow API Models
  version: "1.0.0"
definitions:
  HelloWorldObject:
    type: object
    properties:
      hello: string
      world: string

pom.xml (snippet: project/build/plugins)

<plugin>
  <groupId>io.swagger.codegen.v3</groupId>
  <artifactId>swagger-codegen-maven-plugin</artifactId>
  <version>3.0.2</version>

  <executions>
    <execution>
      <id>generate-source</id>
      <phase>generate-sources</phase>
      <goals>
        <goal>generate</goal>
      </goals>
      <configuration>
        <inputSpec>${basedir}/src/main/swagger/swagger.yaml</inputSpec>
        <configurationFile>${basedir}/src/main/swagger/config.json</configurationFile>
        <language>jaxrs-di</language>
        <apiPackage>${swagger.api.package}</apiPackage>
        <modelPackage>${swagger.model.package}</modelPackage>
        <generateSupportingFiles>false</generateSupportingFiles>
        <modelNameSuffix>Model</modelNameSuffix>
      </configuration>
    </execution>
  </executions>
</plugin>