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:
- It is spread over multiple yaml files
- It can be edited in Swagger Editor
- 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.