can we generate automatic documentation from api gateway

user_5890004 0
Viewed 695

I am using Lambda API gateway REST API with serverless. I want to generate automatic API docs instead of writing manually in open API. I saw this documentation from Amazon https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-export-api.html

When I use this it is not generating Response properly. It generates something like this

responses:
    200:
      description: "200 response"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Empty"

I want to know if there is anything I am doing wrong or if there is any other way to generate docs for serverless API gateway.

Thanks in advance.

aws-api-gateway aws-lambda serverless amazon-web-services api
1 Answers

It looks like you don't have your response modeled. For example, here's how you'd do it with the SAM framework:

https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-resource-api.html#sam-api-gatewayresponses

The export generates an openapi or swagger definition from your api. Then. you can use openapi-generator-cli to generate docs (and also client libraries and other goodies)

for example:

aws apigateway get-export --parameters extensions='apigateway' --rest-api-id abcdefg123 --stage-name dev --export-type oas30 openapi.yaml

then

openapi-generator-cli generate -i openapi.yaml -g html -o doc

See more doc examples here:

https://openapi-generator.tech/docs/generators#documentation-generators

user_72980960
Related