Forum Discussion

sisco's avatar
sisco
New Member
3 months ago

Adding Documentation to my AWS SAM API Gateway

I deployed my SAM application with API Gateway, referencing an external file for DefinitionBody. The deployment succeeded, but in the AWS documentation, I can only see the summary, description, and the responses I defined, not the requestBody. I suspect there may be an issue with how my Swagger file is structured. How can I include the requestBody in the API Gateway documentation?

DefinitionBody:
   Fn::Transform:
      Name: AWS::Include
      Parameters:
         Location: api/swagger-integrated.yaml

In my swagger-integrated.yaml file:

openapi: "3.0.1"
info:
   title: "api-dev"
   version: "v1.0"

paths:
   /efectos:
      post:
         summary: Start extraction
         description: Extracts the data
         parameters:
            -in: body
            name: payload
            description: test payload
             schema:
                 $ref: "#/components/schemas/test"
         responses:
            200:
               description: "200 response"
                content: { }
          x-amazon-apigateway-integration:
             uri: Fn::Sub: arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${ExtractLambda.Arn}/invocations
             responses:
                default:
                    statusCode: "200"
             httpMethod: "POST"
             type: "aws_proxy"

Then my schema is set below in components:

components:
  schemas:
    test:
      type: object
      properties:
        Envio:
          type: object
          properties:
            proyecto:
              type: string
            lote:
              type: integer
            orden:
              type: integer
            magnitud:
              type: integer
            Fichero0:
              type: object
              properties:
                iddocumento:
                  type: integer
                data:
                  type: string
                  format: base64

 

1 Reply

Sort By
  • BookerE1's avatar
    BookerE1
    Occasional Visitor
    3 months ago

    Hello,

     

    I understand that you want to include the requestBody in the API Gateway documentation for your SAM application. I did some research and found a possible solution for you.

    you can use the x-amazon-apigateway-documentation extension in your Swagger file to add documentation content for individual API entities, such as parameters, responses, models, and authorizers. You can use this extension to specify the documentation properties for the requestBody, such as description, summary, and example. Dog Needs Best

    paths:
      /request:
        post:
          summary: A sample request
          description: This is a sample request 
          parameters:
            - name: methodRequestHeaderParam
              in: header
              required: true
              type: string
              x-amazon-apigateway-documentation:
                description: This is a header parameter
                summary: A header parameter
            - name: methodRequestQueryParam
              in: query
              required: false
              type: string
              x-amazon-apigateway-documentation:
                description: This is a query parameter
                summary: A query parameter
          requestBody:
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/LoginForm'
            x-amazon-apigateway-documentation:
              description: This is the request body
              summary: A request body
              example: |
                {
                  "username": "user",
                  "password": "pass"
                }
          responses:
            '200':
              description: A successful response
              x-amazon-apigateway-documentation:
                description: This is a successful response
                summary: A success

     

    After adding the x-amazon-apigateway-documentation extension to your Swagger file, you need to redeploy your SAM application and check the API Gateway documentation for your API. You should be able to see the request body documentation along with the other documentation content.

    I hope this helps you solve your problem. If you have any other questions, feel free to ask me. 

     

    Best Regard,
    BrookE1