Open API specs with more than one YAML file

Everyone that has ever documented a REST API knows what it feels like to write an entire YAML file complete with all those resources, paths, requests and schemas, but suddenly you find yourself keeping a file in which the last line has 5 digits length. Yes, it is painful.

Since the best applications are those we built to ourselves, I found myself on this exact same spot documenting an API at work and I searched a lot to not find one single viable solution to this problem, that's when our programmer instincts come in and we spend five times the time we were supposed to building a new tool for ourselves. That's exactly what I did and I want to share with you all a brand new tool written in Go to merge your YAML files on a single boss file to be used as your OpenAPI spec.

Introducing: GOpenAPI

GOpenAPI (Golang OpenAPI) is a tool that uses a file called dirs.json to scan files and directories (yes, whole directories worth of yaml) into one single swagger.yaml file at the end of execution.

You can check the source code here. Note that the repository is also a template that can be cloned and used as a draft to create your first OpenAPI spec with this tool (just make sure to keep gopenapi folder if you are not willing to install it via go install, otherwise it is completely removable)

How does it works (and do I get it working)

Simple, once you run gopenapi it reads the dirs.json file and starts to build an OpenAPI spec with all the files and folders declared in there. Note that the dirs.json will use files for unique keys such as info, servers and security as well as a key called template (which is just a blank OpenAPI yaml file)

Resources and keys that are hard to keep in a single file (such as paths, schemas and requests) can be stored in folders, and those can also be mentioned using the common #ref tag on OpenAPI, since all of them are going to the same file after merged.

This project also comes with an index.html that can be served statically and it also interacts with the Swagger UI official bundle that is contained inside the dist folder.

That's all folks

I hope this tool comes along for anybody who (just like me) searched a whole lot of reddits and github repositories just not to find the tool they were looking for. Well, now you have it and it is completely open source which means that, if you see any improvement or issue that can be resolved I won't think twice before collaborating with you to solve it. Also, I am pretty much naive on golang so it might have a lot to improve on this project, I will try to keep it up to date and constantly improve it (since I will also use it a lot now)

Thank you for reading and I hope this one comes handy to you the same way it did to me ;)

The above is the detailed content of Open API specs with more than one YAML file. For more information, please follow other related articles on the PHP Chinese website!