aws-sam-cli
aws-sam-cli copied to clipboard
aws
Add command to generate swagger/OpenAPI from SAM template
Describe your idea/feature/enhancement
SAM CLI should provide a command to generate a swagger/OpenAPI definition file given a SAM template. SAM has this great convenience feature where it authors the swagger/OpenAPI document for you at deploy time. However, there are good reasons why a project would want to have access to the document as part of the build process. One example is if the project wants to use swagger-codegen to generate code from the swagger file. If you want to do this with SAM today, you have to hand-manage the OpenAPI doc yourself rather than let SAM manage it for you.
Proposal
No SAM spec changes should be needed for this, but the SAM translator library should do most of the heavy lifting here and add a library method to fetch the OpenAPI doc for a given SAM template and API logicalId (default to ServerlessRestApi). Then SAM CLI can add a command (sam generate openapi?) that calls this method and outputs the generated OpenAPI doc.
FYI. You can also use OpenAPI Generator to generate API clients, server stubs, documentation, schemas, etc. We just released v4.1.3 last week: https://twitter.com/oas_generator/status/1180123829626003456. Please check it out and let us know if you've any feedback.
Disclosure: I'm the top contributor to both OpenAPI Generator and Swagger Codegen.
Is this feature request asking for SAM to somehow do what apigateway endpoint does? https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-export-api.html#api-gateway-export-api-download-swagger-yaml
GET /restapis/<restapi_id>/stages/<stage_name>/exports/oas30
Host: apigateway.<region>.amazonaws.com
Accept: application/yaml
Is this feature request asking for SAM to somehow do what apigateway endpoint does? https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-export-api.html#api-gateway-export-api-download-swagger-yaml
GET /restapis/<restapi_id>/stages/<stage_name>/exports/oas30 Host: apigateway.<region>.amazonaws.com Accept: application/yaml
Yes, I'd like to be able to generate the swagger docs prior to deploy.
