Setup with Swagger UI and Swagger Editor using yaml split across mutliple files

Viewed 961

I would like to use swagger for our project, which is rather big. Documenting the whole REST-API in one single yaml file would be too much, so I would like to split it into several yaml files. First I tried to use Swagger UI simply by downloading it an opening its index.html. That works until the point that I split the yaml into multiple files, as I got CORS errors then. To circumvent them, I simply deployed the Swagger-UI Folder, with my projects yaml files inside it as artifact to my tomcat. The folder structure of the artifact looked like this:

swagger_ui
├── index.html
└── api
    ├── root.yaml
    ├── paths
    │   ├── path1.yaml
    │   ├── path2.yaml
    │   └── ...
    └── schemas
        ├── schema1.yaml
        ├── schema2.yaml
        └── ...

Now all CORS errors were gone, as my references are now all within the same origin (eg. "http://localhost:8080/swagger_ui") So far, so good.

Now I wanted to have a simple way of editing the files using Swagger Editor. In Swagger Editor, I click on File --> Import URL and import my root.yaml file. Now I get a bunch of errors saying the URLs to "paths" and "schemas" can not be resolved... Which makes sense, as I only imported root.yaml and the path and schema files are stored on a completely different server. So my current approach is to deploy Swagger Editor alongside Swagger UI in my tomcat. The current folder structure looks like this:

swagger_ui
└── index.html
swagger_editor
└── index.html
api
├── root.yaml
├── paths
│   ├── path1.yaml
│   ├── path2.yaml
│   └── ...
└── schemas
    ├── schema1.yaml
    ├── schema2.yaml
    └── ...

I thougt I can use eg. "$ref: '../api/paths/path1.yaml'" to reference the the path1.yaml file from BOTH Swagger UI and Swagger Editor, but I get the Error:

Could not resolve reference: Tried to resolve a relative URL, without having a basePath. path: '../api/paths/path1.yaml' basePath: 'undefined'".

Aside from this error... Using ".." to go up one directory does not seem right in itself...

So the question is: Which is the right way to set up a Swagger API Definition that has the following properties:

  1. It is spread over multiple yaml files
  2. It can be edited in Swagger Editor
  3. It can also simply be visualized in Swagger UI

If my current approach is totaly wrong and there is a completely different approach, please tell me. It is no requirement to use tomcat or anything else I stated above. I just wanted to know if my approach makes any sense at all.

0 Answers
Related