Swagger-editor: Can I split my API over multiple YAML files?

[markewallace]

I'm using YAML format to document an API. Is it possible to split the documentation over multiple YAML e.g. I'd like to have something like this:

parameters_common.yaml - Parameters that are common to a number of API's
parameters_customers.yaml - Parameters that are specific to the Customers API
api_customers.yaml - Customers API (this includes previous two yaml files)

[mohsen1]

From Swagger 2.0 specs standpoint yes, you can. You can have $refs to external files. For example, if your parameters_common.yaml is living in the same folder that your main YAML file is living then you can include that files like this:

swagger: '2.0'
parameters: 
  $ref: parameters_common.yaml
paths: 
 ...

Your parameters_common.yaml would be just the array of parameters

- name: param_one
...
- name: param_two
...

This works fine in current editor if you host the editor yourself so parameters_common.yaml path can get resolved as an HTTP path. Currently there is no way to jump between files or create a new one.
If you are doing a big project with Swagger, I recommend hosting the editor yourself. When editor and the API you are building are on the same origin, XHR call don't have to be cross-origin which help editor to show more details about calls in "try-operation" and your API doesn't have to have cross origin headers.

[newmanw]

Possible support for loading multiple files in the generator in the future?

[mohsen1]

@newmanw Generators for 2.0 usually get one big specs file. If you have multiple files linked to each other (via $ref) you would need to resolve those links and make a large specs file then send it to generator.

[newmanw]

@mohsen1 agree 100% with current model of one complete spec with all models, or hosting the editor yourself to avoid cross-origin. But would be helpful if I could just import the model files into the editor and reference.

Its easier to read/write and I am going to have models that exist in more than one schema (don't really want copy pasta). In some cases would also like to use a model that someone else wrote.

Idea comes from plunker giving users the ability to create multiple files in one 'project'.

Can't say this is doable or even worth the time, just an idea.

[mohsen1]

We thought about it and decided to not make an IDE from Swagger Editor. Swagger Editor can resolve remote and relative $refs. So if you want to have multiple files, host the editor and use a relative path in your $ref to refer to another file hosted in your server. (For example $ref: /my-model.yaml)

There is no end in making Swagger Editor similar to an IDE.

Even with this decision in place, you are more than welcome to spend the time and implement this feature. After all this is an open source project.

[newmanw]

@mohsen1 like I said before I agree with current solutions, did not mean to step on any toes.

As an open source project the idea that I can implement this feature is implied, and I never meant to imply that you should implement it. Your explanation that it was thought about and rejected is enough for me.

:v:

[mohsen1]

I'v written about current state of multi-file Swagger in this blog post

[arnaud-deprez]

Hi @mohsen1

If I get it right, it's currently not possible to edit multiple files in the editor and directly see the result, isn't it ?

The solution you propose doesn't work very well to because it replace all links (even the local ones).
I've an example with multiple composition (allOf) with multiple $refs. And in that case, as it also resolve local links, the editor complains too.
I actually don't know json-refs and I don't know if it possible to avoid resolving local links but it could be a temporary solution.

I also think it could be very nice if the swagger-editor would be able to support a project view with multiple files.

[mohsen1]

Supporting multi-file in editor is something I want to see also. We're discussing it here

Maybe json-refs should allow resolving only file refs and leaving refs with fragment URLs alone. @whitlockjc maintains json-refs.

[arnaud-deprez]

Thx for your quick answer.

@whitlockjc It could be a nice workaround !

[csaftoiu]

Even with $refs, is it to say there's no way to split, say, the list of paths into multiple files? To me that would be a most obvious use case for an API with lots of paths, e.g. one file for /user/..., one file for /item/..., etc. Is there any way to do this? The best I can see would be something like paths: {$ref: /api/paths.yaml}, and paths.yaml would have to include all of them.

Would something like this work?

paths:
    allOf:
        - $ref: /api/users.yaml
        - $ref: /api/items.yaml

[MauOnline]

I am a bit confused.
I can not reference external file in my main documentation file :
Here is my structure:

main-swagger.yaml

paths:
  /myOperation:
     post:
       operationId: myOperation ID
      #Request parameters (scope: query, headers and body)
       parameters:          
           $ref: '../commons/headers.yaml'

commons/headers.yaml

- in: header
  required: false
  name: X-Test
  type: boolean
  description: |
    Common attribute to define if this is a test request that will allow the system to utilize test system or stub implementations rather than the LIVE service.

- in: header
  required: false
  name: X-Debug
  type: boolean
  description: |
    Common attribute to define if the system should log extra information for debugging/testing purpose.

- in: header
  required: false
  name: X-Performance
  type: boolean
  description: |
    Common attribute to define if the system should log performance information for debug/test  purpose.

I got no errors, just parameters are not shown on Swagger-ui. Local Swagger-editor is not able to get relative or absolute URL path.
It seems like YAML implementation doesn't support splitting. Is that the case please ? It only works with JSON ?

Please have a look on this topic:
https://community.apigee.com/questions/6320/aplitting-swaggeryaml-into-multiple-files.html

[fehguy]

Hi, if you're having trouble with the swagger-ui not rendering these parameters, can you please open an issue in that repository? What I see here should be supported.

But in swagger-editor, it doesn't make sense to have a relative file location like ../commons/headers.yaml. Why? Because swagger-editor doesn't have a notion of the location of the spec file. It's meant for being edited in-place, not remotely. Some have suggested that the host should be used along with basePath for relative locations--however that doesn't make sense as that's the location for the API calls, not the specification file.

If you want a reference, the editor needs absolute or local refefrences. Relative ones doesn't make sense

[jeff9finger]

This makes sense, but can an option be created that would allow this if someone really wants to do it? If I know that my spec is on the same system as the API and I am developing the spec, it seems reasonable to allow this as an option.

Would support for this option create other problems?

[fehguy]

Anything that makes assumptions about how you're deploying which is outside of the specification itself is prone to being abused. Can you share more about what you're describing? How would you tell the editor that you're hosting the file at a particular location?

[jeff9finger]

When I'm developing an API, I would like to easily test and inspect the API as a whole using swagger-editor. If my API is large and I have multiple files that define the models, endpoints, etc., this is impossible with swagger-editor.

Currently, I'm trying to do this with swagger-ui. It is very cumbersome. swagger-ui is not really for development of an API, so error reporting is minimal. It is very difficult to determine where an error in my spec might be. I am open to other ideas, but have not really found a good one. Using swagger hub does not really solve my problem because I need to access my reference files from my local network.

What I suggest is a property or some configuration setting that will allow me to specify the base bath for the relative references. Ideally, this would be able to be a remote protocol (like http) or local (like file).

Would that concept work with swagger-editor?

[kgkg]

I also believe more support for splitting swagger api into multiple files should be added both to swagger-ui and swagger-editor. Right now developing api bigger than "petstore" results in breaking DRY rule over and over again.

At least there should be support for importing definitions or paths from another file as a whole, not one by one.

[jeff9finger]

Here is an update on the workaround that we have found...

We have worked around this problem by "normalizing" all the yaml files into one big file as part of the build process. This allows the tools to work on the one big file, but we can still develop and manage the files as separate files.

I believe swagger-codegen has templates for normalizing all the separate files, but we have been using the tool from Reprezen. A great eclipse based tool and the product support is awesome!

[terencechow]

@jeff9finger how does your workaround allow the swagger-editor to edit/view a child file? can you provide more clarity? If it doesn't, are you just reloading your swagger editor every time a child file changes?

[kgkg]

@terencechow you have to copy-paste your files or use multiple browsers.

[codingontheedge]

Isn't it easier to use json all the way (so edit the files directly in json format) to make the linking between the definitions and parameters (model) and the actual API (view) and forget the yaml editor if you want to make your swagger documentation more modular?
I'm also struggling to organize my yaml files without DRY-ing all the time.

[deveshpujari]

Based on @mohsen1 blog. I have written the Java implementation which can be added to your project in your project's pom file.
https://github.com/deveshpujari/swagger-multi-file-yaml

[jeff9finger]

@terencechow (sorry for the really slow response!)
My solution using Reprezen would work with swagger editor only by normalizing all the swagger files into one first, then loading it into swagger-codegen. Not really a good solution for swagger editor.

But we are using Reprezen instead of swagger editor to design our spec. I hope this answers your question.

[francescobianco]

@markewallace @jeff9finger Hi this is my solution to compose multiple YAML files https://github.com/javanile/yamlinc

[boesing]

@francescobianco amazing work there. I've created a feature request since I really would like to use glob paths so I do not need to add hundreds of $include tags in my documentation. 👍

[arsdehnel]

While it's nothing specific to swagger I'm initially having better success with https://www.npmjs.com/package/refs than with the json-refs version noted here.

[hajnalmt]

This is still an issue though. Basically all the solutions generate a swagger from more swagger files.
But I am still unable to use the swagger editor for a splitted swagger file since you are able to edit one file in the editor.

[pmundt]

Instead of saying you have no plans on making swagger-editor an IDE, you should simply state that you have no intention of making swagger-editor compliant with the OpenAPI specification, as this is more truthful. The multi-file split discussed is not an esoteric workload, and one that is fully supported by the specification. The time to complain about this was at the time it was being defined in the spec.

[webron]

@pmundt So you chose to comment on an issue that was opened late 2014 and closed early 2015. I'm not going to comment about whether Swagger Editor will support editing multiple files in the future, because I simply don't know.
That said, while the OpenAPI Specification supports splitting a definition into multiple files, it does not require it. Not supporting it does not make a tool non-compliant.

[spyro2000]

So I got multipe YAML files and cannot edit or even view the API now. Great.