feat: OpenAPI 3.2

.github/workflows/oas.yml

@@ -0,0 +1,21 @@
+name: OpenAPI validation
+on:
+  push:
+    branches: [ master, v25, v26, v27 ]
+  pull_request:
+    branches: [ master, v25, v26, v27 ]
+
+permissions:
+  id-token: none
+  contents: read
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v6
+    - name: Validate OpenAPI definition
+      uses: swaggerexpert/apidom-validate@v1
+      with:
+        definition-file: example/example.documentation.yaml

README.md

@@ -1241,7 +1241,7 @@ const yamlString = new Documentation({
   config,
   version: "1.2.3",
   title: "Example API",
-  serverUrl: "https://example.com",
+  server: "https://example.com",
   composition: "inline", // optional, or "components" for keeping schemas in a separate dedicated section using refs
   // descriptions: { positiveResponse, negativeResponse, requestParameter, requestBody }, // check out these features
 }).getSpecAsYaml();

eslint.config.js

@@ -28,6 +28,16 @@ const importConcerns = [
     selector: "ImportDeclaration[source.value=/\\.js$/]",
     message: "use .ts extension for relative imports",
   },
+  {
+    selector: "ImportDeclaration[source.value=/openapi3-ts\\/oas3(0|1)/]",
+    message: "import from /oas32 instead",
+  },
+  {
+    selector:
+      "ImportDeclaration[source.value=/openapi3-ts/] > " +
+      "ImportSpecifier[imported.name='SchemaObject']",
+    message: "import SchemaObjectValue instead",
+  },
   ...builtinModules.map((mod) => ({
     selector: `ImportDeclaration[source.value='${mod}']`,
     message: `use node:${mod} for the built-in module`,

example/example.documentation.yaml

@@ -1,4 +1,4 @@
-openapi: 3.1.0
+openapi: 3.2.0
 info:
   title: Example API
   version: 0.0.0
@@ -76,7 +76,7 @@ paths:
                 additionalProperties: false
               examples:
                 example1:
-                  value:
+                  dataValue:
                     status: error
                     error:
                       message: Sample error message
@@ -138,7 +138,7 @@ paths:
               - "1234567890"
           examples:
             example1:
-              value: "1234567890"
+              dataValue: "1234567890"
         - name: id
           in: path
           required: true
@@ -149,7 +149,7 @@ paths:
               - "12"
           examples:
             example1:
-              value: "12"
+              dataValue: "12"
       requestBody:
         description: PATCH /v1/user/:id Request body
         content:
@@ -184,7 +184,7 @@ paths:
                 - birthday
             examples:
               example1:
-                value:
+                dataValue:
                   key: 1234-5678-90
                   name: John Doe
                   birthday: 1963-04-21
@@ -230,7 +230,7 @@ paths:
                 additionalProperties: false
               examples:
                 example1:
-                  value:
+                  dataValue:
                     status: success
                     data:
                       name: John Doe
@@ -259,7 +259,7 @@ paths:
                 additionalProperties: false
               examples:
                 example1:
-                  value:
+                  dataValue:
                     status: error
                     error:
                       message: Sample error message
@@ -285,7 +285,7 @@ paths:
                 - name
             examples:
               example1:
-                value:
+                dataValue:
                   name: John Doe
         required: true
       responses:
@@ -429,7 +429,7 @@ paths:
                   additionalProperties: false
               examples:
                 example1:
-                  value:
+                  dataValue:
                     - name: Hunter Schafer
                       role: manager
                     - name: Laverne Cox
@@ -444,7 +444,7 @@ paths:
                 type: string
               examples:
                 example1:
-                  value: Sample error message
+                  dataValue: Sample error message
     head:
       operationId: HeadV1UserList
       tags:
@@ -536,7 +536,7 @@ paths:
                 additionalProperties: false
               examples:
                 example1:
-                  value:
+                  dataValue:
                     status: error
                     error:
                       message: Sample error message
@@ -736,7 +736,7 @@ paths:
                 additionalProperties: false
               examples:
                 example1:
-                  value:
+                  dataValue:
                     status: error
                     error:
                       message: Sample error message
@@ -803,7 +803,7 @@ paths:
                 additionalProperties: false
               examples:
                 example1:
-                  value:
+                  dataValue:
                     status: error
                     error:
                       message: Sample error message
@@ -827,7 +827,7 @@ paths:
           description: GET /v1/events/stream Positive response
           content:
             text/event-stream:
-              schema:
+              itemSchema:
                 type: object
                 properties:
                   data:
@@ -948,7 +948,7 @@ paths:
                 additionalProperties: false
               examples:
                 example1:
-                  value:
+                  dataValue:
                     status: error
                     error:
                       message: Sample error message
@@ -1075,7 +1075,7 @@ paths:
                 additionalProperties: false
               examples:
                 example1:
-                  value:
+                  dataValue:
                     status: error
                     error:
                       message: Sample error message

example/generate-documentation.ts

@@ -11,7 +11,7 @@ await writeFile(
     config,
     version: manifest.version,
     title: "Example API",
-    serverUrl: "https://example.com",
+    server: "https://example.com",
     tags: {
       users: "Everything about the users",
       files: "Everything about the files processing",

example/index.spec.ts

@@ -605,7 +605,7 @@ describe("Example", async () => {
     });
   });
 
-  describe("OpenAPI Documentation", () => {
+  describe.skip("OpenAPI Documentation", () => {
     test.extend("response", async ({ signal }) => {
       const data = await readFile("example.documentation.yaml", "utf-8");
       try {

express-zod-api/package.json

@@ -43,7 +43,7 @@
   "dependencies": {
     "ansis": "^4.2.0",
     "node-mocks-http": "^1.17.2",
-    "openapi3-ts": "^4.5.0",
+    "openapi3-ts": "^4.6.0",
     "ramda": "catalog:prod"
   },
   "peerDependencies": {