Missing or incorrect API endpoint definitions

Oct 13, 2025 by thesweetdesigns.com 149 views

Introduction

When publishing a Serverless Application Model (SAM) application to AWS Serverless Application Repository (SAR), you may encounter an error indicating an "Invalid OpenApi document." This issue can be frustrating, especially when your application deploys successfully using sam deploy but fails to publish to SAR. In this article, we will delve into the possible causes of this error and provide step-by-step troubleshooting guidance to help you resolve the issue.

Understanding the Error

The error message typically looks like this:

Error: Invalid Serverless Application Model (SAM) application

Or, more specifically:

Error: Invalid OpenApi document

This error suggests that there is a problem with the OpenApi document in your SAM application. OpenApi is a specification for describing RESTful APIs, and it is used by SAM to define the API endpoints and their corresponding HTTP methods.

Possible Causes of the Error

There are several possible causes of the "Invalid OpenApi document" error when publishing a SAM application to SAR:

Incorrect OpenApi version: Make sure that the OpenApi version in your SAM application matches the version expected by SAR. As of this writing, SAR supports OpenApi 3.0.2.
Missing or incorrect API endpoint definitions: Ensure that all API endpoints are properly defined in the OpenApi document. This includes the HTTP method, path, and any required query parameters or request body.
Invalid API endpoint syntax: Verify that the API endpoint syntax is correct and follows the OpenApi specification.
Missing or incorrect API documentation: Ensure that all API endpoints have proper documentation, including descriptions, parameter definitions, and response definitions.
Conflicting or duplicate API endpoint definitions: Check for any conflicting or duplicate API endpoint definitions in the OpenApi document.

Troubleshooting Steps

To troubleshoot the "Invalid OpenApi document" error, follow these steps:

Step 1: Review the OpenApi Document

Carefully review the OpenApi document in your SAM application to ensure that it is correct and complete. Check for any missing or incorrect API endpoint definitions, invalid API endpoint syntax, or missing API documentation.

Step 2: Verify the OpenApi Version

Verify that the OpenApi version in your SAM application matches the version expected by SAR (3.0.2). You can do this by checking the openapi property in the template.yaml file.

openapi: 3.0.2

Step 3: Check API Endpoint Definitions

Ensure that all API endpoints are properly defined in the OpenApi document. This includes the HTTP method, path, and any required query parameters or request body.

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  paths:
    /users:
      get:
        summary: Get all users
        description: Returns a list of all users
        responses:
          200:
            description: A list of users
            content:
              application/json:
                schema:
                  type: array
                  items:
                    $ref: '#/components/schemas/User'

Step 4: Validate the OpenApi Document

Use an OpenApi validation tool, such as OpenApi Validator, to validate the OpenApi document in your SAM application. This can help identify any syntax errors or invalid definitions.

Step 5: Publish the SAM Application to SAR

Once you have verified the OpenApi document and made any necessary corrections, try publishing the SAM application to SAR again.

Conclusion

The "Invalid OpenApi document" error when publishing a SAM application to SAR can be frustrating, but it is often caused by a simple mistake in the OpenApi document. By following the troubleshooting steps outlined in this article, you should be able to identify and resolve the issue, ensuring that your SAM application publishes successfully to SAR.

Additional Resources

AWS SAM Documentation
AWS SAR Documentation
OpenApi Specification
OpenApi Validator
Frequently Asked Questions: Invalid OpenApi Document when Publishing SAM App to SAR ====================================================================================

Q: What is the cause of the "Invalid OpenApi document" error when publishing a SAM application to SAR?

A: The "Invalid OpenApi document" error can be caused by a variety of issues, including incorrect OpenApi version, missing or incorrect API endpoint definitions, invalid API endpoint syntax, missing or incorrect API documentation, and conflicting or duplicate API endpoint definitions.

Q: How do I verify the OpenApi version in my SAM application?

A: To verify the OpenApi version in your SAM application, check the openapi property in the template.yaml file. The version should match the version expected by SAR, which is currently 3.0.2.

openapi: 3.0.2

Q: What is the correct syntax for defining API endpoints in the OpenApi document?

A: The correct syntax for defining API endpoints in the OpenApi document is as follows:

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  paths:
    /users:
      get:
        summary: Get all users
        description: Returns a list of all users
        responses:
          200:
            description: A list of users
            content:
              application/json:
                schema:
                  type: array
                  items:
                    $ref: '#/components/schemas/User'

Q: How do I validate the OpenApi document in my SAM application?

A: To validate the OpenApi document in your SAM application, use an OpenApi validation tool, such as OpenApi Validator. This can help identify any syntax errors or invalid definitions.

Q: What is the difference between the `openapi` property and the `swagger` property in the `template.yaml` file?

A: The openapi property and the swagger property are both used to define the OpenApi document in the template.yaml file. However, the openapi property is used to specify the OpenApi version, while the swagger property is used to specify the Swagger UI configuration.

openapi: 3.0.2
swagger:
  title: My API
  description: My API description
  version: 1.0.0

Q: Can I use a different OpenApi version than 3.0.2 in my SAM application?

A: Yes, you can use a different OpenApi version than 3.0.2 in your SAM application. However, you must ensure that the version you choose is supported by SAR.

Q: How do I troubleshoot the "Invalid OpenApi document" error when publishing a SAM application to SAR?

A: To troubleshoot the "Invalid OpenApi document" error when publishing a SAM application to SAR, follow these steps:

Review the OpenApi document in your SAM application to ensure that it is correct and complete.
Verify the OpenApi version in your SAM application.
Check API endpoint definitions to ensure that they are properly defined.
Validate the OpenApi document using an OpenApi validation tool.
Publish the SAM application to SAR again.

Q: What are some common mistakes that can cause the "Invalid OpenApi document" error when publishing a SAM application to SAR?

A: Some common mistakes that can cause the "Invalid OpenApi document" error when publishing a SAM application to SAR include:

Incorrect OpenApi version
Missing or incorrect API endpoint definitions
Invalid API endpoint syntax
Missing or incorrect API documentation
Conflicting or duplicate API endpoint definitions

Q: Can I use a third-party tool to generate the OpenApi document for my SAM application?

A: Yes, you can use a third-party tool to generate the OpenApi document for your SAM application. However, you must ensure that the tool generates a valid OpenApi document that meets the requirements of SAR.

Q: How do I update the OpenApi document in my SAM application after making changes to the API?

A: To update the OpenApi document in your SAM application after making changes to the API, follow these steps:

Review the changes made to the API.
Update the OpenApi document to reflect the changes.
Validate the OpenApi document using an OpenApi validation tool.
Publish the SAM application to SAR again.

Q: Can I use a different API description format than OpenApi in my SAM application?

A: Yes, you can use a different API description format than OpenApi in your SAM application. However, you must ensure that the format you choose is supported by SAR.

Q: How do I troubleshoot issues with the OpenApi document in my SAM application?

A: To troubleshoot issues with the OpenApi document in your SAM application, follow these steps:

Review the OpenApi document to ensure that it is correct and complete.
Verify the OpenApi version in your SAM application.
Check API endpoint definitions to ensure that they are properly defined.
Validate the OpenApi document using an OpenApi validation tool.
Publish the SAM application to SAR again.