v0.13.0-rc.1 - see CHANGELOG for details

Author: Thesephi

CHANGELOG.md

@@ -5,13 +5,17 @@
 - Laxer usage of `ControllerMethodArgs` decorator: now allowing `queries`,
   `params`, `header` as literal arguments, so that things still work even if
   users accidentally / deliberately use the undocumented singular / plural forms
+- Support for Open API Spec v3.1
+- Support for `operationId` and `tags` in OAS path request declarations
+- Support for top-level `tags` in OAS document
 
 ### Changed
 
 - switched from `deps.ts` and `dev_deps.ts` to `deno.jsonc`
 - revamped documentation (JSDoc)
 - code format & code format settings for VS Code users
-- upgraded dependencies (`zod@^3.24.1`)
+- upgraded dependencies (`zod@^3.24.1`, `@std/assert@^1.0.10`,
+  `@std/testing@^1.0.8`)
 - updated typing for `OakOpenApiSpec` (added prop: `request`, untyped unproven
   prop: `requestBody`)
 

deno.jsonc

@@ -1,6 +1,6 @@
 {
   "name": "@dklab/oak-routing-ctrl",
-  "version": "0.13.0-alpha.2",
+  "version": "0.13.0-rc.1",
   "exports": {
     ".": "./mod.ts",
     "./mod": "./mod.ts"
@@ -22,10 +22,10 @@
   "imports": {
     "@asteasolutions/zod-to-openapi": "npm:@asteasolutions/zod-to-openapi@^7.3.0",
     "@oak/oak": "jsr:@oak/oak@^17.1.3",
-    "@std/assert": "jsr:@std/assert@^1.0.9",
+    "@std/assert": "jsr:@std/assert@^1.0.10",
     "@std/io": "jsr:@std/io@^0.225.0",
     "@std/path": "jsr:@std/path@^1.0.8",
-    "@std/testing": "jsr:@std/testing@^1.0.6",
+    "@std/testing": "jsr:@std/testing@^1.0.8",
     "zod": "npm:zod@^3.24.1"
   },
   "fmt": {

deno.lock

@@ -1,6 +1,6 @@
 export const snapshot = {};
 
-snapshot[`useOas standard behavior > testApiDocSnapshot 1`] = `
+snapshot[`useOas standard behavior - OpenApi v3.0 > testApiDocSnapshot 1`] = `
 {
   components: {
     parameters: {},
@@ -15,6 +15,7 @@ snapshot[`useOas standard behavior > testApiDocSnapshot 1`] = `
   paths: {
     "/hello/{name}": {
       post: {
+        operationId: undefined,
         parameters: [
           {
             in: "path",
@@ -26,6 +27,7 @@ snapshot[`useOas standard behavior > testApiDocSnapshot 1`] = `
           },
         ],
         responses: {},
+        tags: undefined,
       },
     },
   },
@@ -34,5 +36,65 @@ snapshot[`useOas standard behavior > testApiDocSnapshot 1`] = `
       url: "/mock/",
     },
   ],
+  tags: [
+    {
+      description: "Example description for Example Section",
+      externalDocs: {
+        url: "http://localhost",
+      },
+      name: "Example Section",
+    },
+  ],
+}
+`;
+
+snapshot[`useOas standard behavior - OpenApi v3.1 > testApiDocSnapshot 1`] = `
+{
+  components: {
+    parameters: {},
+    schemas: {},
+  },
+  info: {
+    description: "this is a mock API",
+    title: "mock API",
+    version: "0.1.0",
+  },
+  openapi: "3.1.0",
+  paths: {
+    "/hello/{name}": {
+      post: {
+        operationId: "my-unique-test-op-id",
+        parameters: [
+          {
+            in: "path",
+            name: "name",
+            required: true,
+            schema: {
+              type: "string",
+            },
+          },
+        ],
+        responses: {},
+        tags: [
+          "Example Section",
+        ],
+      },
+    },
+  },
+  servers: [
+    {
+      url: "/mock/",
+    },
+  ],
+  tags: [
+    {
+      description: "Example description for Example Section",
+      externalDocs: {
+        url: "http://localhost",
+      },
+      name: "Example Section",
+    },
+  ],
+  webhooks: {},
 }
 `;

src/__snapshots__/useOas_test.ts.snap

@@ -3,8 +3,12 @@ import type { OakOpenApiSpec } from "./utils/schema_utils.ts";
 import type { SupportedVerb } from "./Store.ts";
 import { debug } from "./utils/logger.ts";
 
+type TheRouteConfig = RouteConfig & {
+  tags?: string[];
+};
+
 // fnName|method|path => OasRouteConfig
-export const oasStore: Map<string, RouteConfig> = new Map();
+export const oasStore: Map<string, TheRouteConfig> = new Map();
 
 const getRouteId = (
   fnName: string,
@@ -62,6 +66,8 @@ export const updateOas = (
       ...existing.responses,
       ...specs?.responses,
     },
+    operationId: specs?.operationId,
+    tags: specs?.tags,
   };
 
   debug(`OpenApiSpec: recording for [${method}] ${path}`);

src/oasStore.ts

@@ -2,6 +2,7 @@ import type { Application } from "@oak/oak";
 import { oasStore } from "./oasStore.ts";
 import {
   OpenApiGeneratorV3,
+  OpenApiGeneratorV31,
   OpenAPIRegistry,
   type RouteConfig,
 } from "@asteasolutions/zod-to-openapi";
@@ -34,6 +35,11 @@ export type UseOasConfig = Partial<OpenAPIObjectConfig> & {
   jsonPath?: string;
   uiPath?: string;
   uiTemplate?: string;
+  tags?: {
+    name: string;
+    description?: string;
+    externalDocs?: { url: string };
+  }[];
 };
 
 type UseOas = (
@@ -62,7 +68,11 @@ const _useOas: UseOas = (
     }
   });
 
-  const generator = new OpenApiGeneratorV3(registry.definitions);
+  const OpenApiGenerator = oasCfg.openapi?.startsWith("3.0")
+    ? OpenApiGeneratorV3
+    : OpenApiGeneratorV31;
+
+  const generator = new OpenApiGenerator(registry.definitions);
   const apiDoc = generator.generateDocument({
     openapi: "3.0.0",
     info: {