在许多文件中分割招摇的定义 [英] splitting swagger definition across many files

问题描述

问题:如何在文件中分割大写字母定义?该领域有哪些可能性?问题细节如​​下所述:

Question: how can I split swagger definition across files? What are the possibilities in that area? The question details are described below:

我确实有RAML的经验，例如:

I do have experience in RAML and what I do is, 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

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

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

我从中受益的是:

• 由于架构不是内联的，因此我的合同更加清晰，易于维护
• 但这确实很重要:我可以在其他工具中重用架构文件来进行验证，模拟生成，存根，生成测试等.换句话说，通过这种方式，我可以在协定(RAML，这种情况下)和其他工具(非RAML，非可伸缩性，仅基于JSONschema的工具)中重用架构文件.

• I get my contract more clear and easier to maintain, because schemas are not inline
• but that's really important: I can reuse the schema files within other tools to do validation, mock generation, stubs, generate tests, etc. In other words, this way I can reuse schema files within both contract (RAML, this case) and other tools (non-RAML, non-swagger, just JSONschema-based ones).

据我所知，swagger支持$ref关键字，该关键字允许加载外部文件.但是这些文件是通过HTTP/AJAX提取的还是仅仅是本地文件?

As far as I read, swagger supports $ref keyword which allows to load external files. But is that files fetched through HTTP/AJAX or can they just be local files?

那是整个规范所支持的还是仅仅是一些支持它的工具而有些则不支持?

And is that supported by the whole specification or is it just some tools that support it and some that don't?

我在此处发现的是，swagger的输入必须成为一个文件.对于大型项目，这是极为不便的:

What I found here is that the input for swagger has to be one file. And this is extremely inconvenient for big projects:

• 由于尺寸
• 并且因为如果我想使用一些非摇摇欲坠的东西就无法重用该模式

或者换句话说，就分裂文件而言，我可以用摇摇晃晃来达到与RAML一样的效果吗?

Or, in other words, can I achieve the same with swagger, that I can with RAML - in terms of splitting files?

推荐答案

规范允许在多个位置进行引用，但在各处不.这些引用的解析取决于规范的托管位置以及您要执行的操作.

The specification allows for references in multiple locations but not everywhere. These references are resolved depending on where the specification is being hosted--and what you're trying to do.

对于渲染动态用户界面之类的东西，是的，您确实需要最终将整个定义加载到可能由许多文件组成的单个对象"中.如果执行代码生成，则可以直接从文件系统中加载定义.但是最终还是有swagger解析器来进行解析，与其他定义格式相比，在Swagger中它的粒度和可控性要好得多.

For something like rendering a dynamic user interface, then yes you do need to eventually load the entire definition into "a single object" which may be composed from many files. If performing a code generation, the definitions may be loaded directly from the file system. But ultimately there are swagger parsers doing the resolution, which is much more fine grained and controllable in Swagger than other definition formats.

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

In your case, you would use a JSON pointer to the schema reference:

responses:
  200:
    description: the response
    schema:

通过本地参考

      $ref: '#/definitions/myModel'

通过绝对引用:

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

通过相对引用，即相对于此文档的加载位置"

via relative reference, which would be 'relative to where this doc is loaded'

      $ref: 'resource.json#/myModel

通过内联定义

      type: object
      properties:
        id:
          type: string

这篇关于在许多文件中分割招摇的定义的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！