openapi-routes

Sørg for at alle backend-rutefiler bruker OpenAPI-typede rutedefinisjoner.

Regeldetaljer

Når et backend-rammeverk støtter OpenAPI-integrasjon (f.eks. @hono/zod-openapi), omgår rå HTTP-metodebehandlere (.get(), .post()) skjemavalidering og dokumentasjonsgenerering. Denne regelen sjekker at rutefiler importerer OpenAPI-integrasjonen og bruker .openapi() i stedet for rå metoder.

Eksempler på feil kode

packages/backend/src/routes/users.ts

import { Hono } from "hono";

const app = new Hono();

app.get("/users", async (c) => {
  // No OpenAPI schema, no auto-generated docs
  return c.json(await getUsers());
});

Eksempler på riktig kode

packages/backend/src/routes/users.ts

import { OpenAPIHono, createRoute, z } from "@hono/zod-openapi";

const route = createRoute({
  method: "get",
  path: "/users",
  responses: {
    200: {
      content: { "application/json": { schema: UserListSchema } },
      description: "List of users",
    },
  },
});

app.openapi(route, async (c) => {
  return c.json(await getUsers());
});

Regelimplementasjon

/// <reference path="../rules.d.ts" />

export default {
  rules: {
    "openapi-route-completeness": {
      description:
        "All backend routes must use @hono/zod-openapi, not raw HTTP methods",
      async check(ctx) {
        const routeFiles = await ctx.glob("packages/backend/src/routes/*.ts");

        for (const file of routeFiles) {
          if (file.includes(".test.") || file.includes(".spec.")) continue;

          const content = await ctx.readFile(file);

          const importsOpenApi = /from\s+["']@hono\/zod-openapi["']/.test(
            content
          );
          const hasRawMethods = /\.(?:get|post|put|delete|patch)\s*\(/.test(
            content
          );
          const hasOpenApiCalls = /\.openapi\s*\(/.test(content);

          if (!importsOpenApi && hasRawMethods) {
            ctx.report.violation({
              message: `Route file uses raw HTTP methods without importing @hono/zod-openapi`,
              file,
              fix: "Import from @hono/zod-openapi and use .openapi() instead of raw .get()/.post()",
            });
          }

          if (importsOpenApi && hasRawMethods && !hasOpenApiCalls) {
            ctx.report.violation({
              message: `Route file imports @hono/zod-openapi but uses raw HTTP methods instead of .openapi()`,
              file,
              fix: "Replace raw .get()/.post() calls with .openapi() route definitions",
            });
          }
        }
      },
    },
  },
} satisfies RuleSet;

Når du bør bruke den

Når backend-rammeverket ditt støtter OpenAPI-integrasjon og du vil sikre at alle ruter er dokumentert og skjemavalidert. Tilpass importmønsteret og metodedeteksjonen for ditt rammeverk:

// For Express with express-openapi-validator
/from\s+["']express-openapi-validator["']/

// For Fastify with @fastify/swagger
/from\s+["']@fastify\/swagger["']/

Når du ikke bør bruke den

Når ikke alle ruter krever OpenAPI-dokumentasjon (f.eks. interne helsesjekker, metrikk-endepunkter), eller når OpenAPI-spesifikasjoner vedlikeholdes separat fra rutekoden.