How to use openapi3 json specification to validate if Express application has set up correct routes?

Summary

I use orval to generate frontend code in order to fetch data from the backend. The API specification is using the openapi 3 format.

I want to be able to automatically validate if my express backend is implementing the correct endpoints by comparing the specification with the actual implementation.

Example

Let's assume that this is the specification api.json:

{
  "openapi": "3.0.0",
  "info": {
    "version": "1.0.0",
    "title": "My Service"
  },
  "servers": [
    {
      "url": "http://my.service.com/api"
    }
  ],
  "paths": {
    "/my-endpoint": {
      "get": {
        "summary": "List all things",
        "operationId": "listThings",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Thing"
                }
              }
            }
          },
          "default": {
            "description": "unexpected error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Thing": {
        "type": "object",
        "required": [
          "id",
          "name"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "code",
          "message"
        ],
        "properties": {
          "code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}

Orval generates frontend code to fetch defined endpoints via axios and the according Typescript interfaces for request and response data.

So far so good.

Problem

My express backend does not know about the openapi specification. I need to manually create the correct express endpoints and make sure that they return the correct HTTP codes, correct response types and correct error handling.

I learned there are code generators like swagger-routes-express, but my concern with those is that they hide the endpoint definition and that it could be difficult to implement extra business logic to those endpoints. I may be wrong here, but i still didn't get how that would work in this scenario.

Desired solution

I think there are two variants that would be a great outcome:

  1. A code generator that parses the api.json above and generates correct endpoints with proper Typescript types. It needs to be able to accept custom code in those endpoints which shouldn't be overwritten the next time the specification changes and code is regenerated.
  2. A linter that checks the code if the correct endpoints exist and have the correct request and response types. Maybe a set of eslint rules.

Is there anything out there i could use for this?



Read more here: https://stackoverflow.com/questions/68488615/how-to-use-openapi3-json-specification-to-validate-if-express-application-has-se

Content Attribution

This content was originally published by alp at Recent Questions - Stack Overflow, and is syndicated here via their RSS feed. You can read the original post over there.

%d bloggers like this: