Why use the doc as the template?
Seems needlessly complicated. You can comment / document in yml which is supported by the `aws` tooling.
Seems needlessly complicated. You can comment / document in yml which is supported by the `aws` tooling.
You just have to put your domain objects as JSON or YAML in the document.
That will generate 200+ lines of Swagger specification with CRUD operations.
You can then add the documentation you are talking about.
The trick is building out the swagger file with the AWS x-* integrations. That takes the most time. This tool attempts to solve that.
Let me know if I've answered your question!
Really, what drove the creation of this tool and its particular way of doing things are the following motivations:
1) It takes a long time to write a Swagger document by hand (2-4 API operations per resource, 5+ resources on average = 20+ operations)
2) The normal swagger file is 200 - 1000+ lines long. Most of the swagger documents I write (even before including documentation) easily stretch past 1000 lines.
3) To avoid writing 1000 lines of code by hand, this tool lets you define just your domain models, as JSON schemas. If you write the objects that your API will expose, the tool will generate the operations and the swagger code for that automatically.
4) Now that the swagger file is generated, I can fill in documentation and make other changes before deploying.
5) The reason the schemas are in a markdown document is because it easily exports to HTML or a PDF, and is shareable to non-technical users and other audiences (business/product owners/architecture) and keeps everything tidy and in one place.
I agree that having the raw JSON/yaml files are probably easier to work with across tools or as input to other processes. I may add this in the future.
Thanks for giving me the opportunity to explain.