Swagger 引用外部文件中的定义

Question

我有很多 swagger 文件，使用相同的定义。我想将此定义移动到一个单独的文件并引用它们。

主要 swagger 文件如下所示:

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

我尝试导入的文件保存到 exceptions.yaml(并保存到同一位置)，看起来像:

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

我读过 $ref https://swagger.io/docs/specification/using-ref/但找不到如何导入定义，而不是 API

我正在尝试通过以下更改导入它:

    '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

或者在不同的变体中使用相对路径

    '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 ->

或在现有声明下插入 $ref:

definitions:
   $ref: 'exceptions.yaml'  

被完全忽略了

有没有人解决过类似的问题？

Answer 1

这适用于我的文件。我确保 swagger.yaml 和 definition.yaml 位于同一目录中。

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(代码段: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>