Here's a simple CLI tool that gets a full CRUD API up and running in AWS in under 30 seconds.
I design APIs all day, and find myself spending hours just writing the initial Swagger API specification file.
With this tool, I just have to define a couple of schemas in a Markdown document, run generate + deploy, and I'm up and running in AWS with an endpoint I can hit. Needless to say, this saves me countless hours.
I hope it is useful for you all as well. I always get so much value out of HN, and am wanting to give back. Free forever + open source. Concerns/suggestions are welcomed!
Not really... why not have your objects as individual json or yml files instead of embedding them inside a markdown document? You're needlessly complicating the tool (both in terms of the usage and the tool itself)
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.
14 comments
[ 2.6 ms ] story [ 39.4 ms ] threadHere's a simple CLI tool that gets a full CRUD API up and running in AWS in under 30 seconds.
I design APIs all day, and find myself spending hours just writing the initial Swagger API specification file.
With this tool, I just have to define a couple of schemas in a Markdown document, run generate + deploy, and I'm up and running in AWS with an endpoint I can hit. Needless to say, this saves me countless hours.
I hope it is useful for you all as well. I always get so much value out of HN, and am wanting to give back. Free forever + open source. Concerns/suggestions are welcomed!
Thanks for reading.
I've opened a GitHub issue to track this item. I should be able to get it done by the end of the week.
Check this link to see my progress: https://github.com/khalidx/resource-x/issues/1
Thanks for the suggestion!
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.
Maybe I'll rename it before it goes viral and I become famous ;).