在许多文件中拆分swagger定义

Question

问题:如何跨文件拆分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

最后两行在这里非常重要!include <filepath>- 在RAML中有- 我可以将我的整个合同拆分成许多文件,这些文件只是由RAML解析器动态包含(并且所有基于RAML的工具都使用RAML解析器).

我的好处是:

• 我的合同更清晰,更容易维护,因为模式不是内联的
• 但这非常重要:我可以在其他工具中重用模式文件来进行验证,模拟生成,存根,生成测试等.换句话说,这样我就可以在契约(RAML,本例)和其他工具(非RAML,非swagger,只是基于JSONschema的工具)中重用模式文件.

回到Swagger

据我所知,swagger支持$ref允许加载外部文件的关键字.但是这些文件是通过HTTP/AJAX获取的还是只是本地文件？

并且是整个规范支持还是只是一些支持它的工具,而有些工具不支持它？

我在这里发现,swagger的输入必须是一个文件.这对大型项目来说非常不方便:

• 因为大小
• 因为如果我想使用非招摇的东西,我就无法重用架构

或者,换句话说,我可以用摇摆乐来实现同样的目标 - 我可以用RAML - 在分割文件方面吗？

Answer 1

该规范允许在多个位置引用但不是在任何地方引用.这些引用的解析取决于托管规范的位置 - 以及您要执行的操作.

对于像渲染动态用户界面之类的东西,那么是的,你需要最终将整个定义加载到"单个对象"中,该对象可以由许多文件组成.如果执行代码生成,则可以直接从文件系统加载定义.但最终有一些摇摆解析器在进行分辨率,这在Swagger中比其他定义格式更细粒度和可控制.

在您的情况下,您将使用指向架构引用的JSON指针:

responses:
  200:
    description: the response
    schema:

通过本地参考

      $ref: '#/definitions/myModel'

通过绝对参考:

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

通过相对引用,这将是'相对于此doc加载的位置'

      $ref: 'resource.json#/myModel

通过内联定义

      type: object
      properties:
        id:
          type: string