{"_id":"@apexjs-org/openapi","_rev":"5-ff664575b9348dd8ea606aa8e15748f3","name":"@apexjs-org/openapi","dist-tags":{"latest":"1.0.4"},"versions":{"1.0.0":{"name":"@apexjs-org/openapi","version":"1.0.0","author":{"name":"apexjs-org"},"license":"MIT","_id":"@apexjs-org/openapi@1.0.0","maintainers":[{"name":"apexjs-org","email":"koen@kbim.nl"}],"homepage":"https://github.com/apexjs-org/openapi#readme","bugs":{"url":"https://github.com/apexjs-org/openapi/issues"},"dist":{"shasum":"c26f685aafc653b20a585b4e54fe0432a7082931","tarball":"https://registry.npmjs.org/@apexjs-org/openapi/-/openapi-1.0.0.tgz","fileCount":28,"integrity":"sha512-4LHHpzXkiJ692u8q5tSGaWw0H1mLy47nOQuznwhUwc35av+W6S4CRSG3XwA9rpm6vYoKMVEFQi5EC9dc6Gv3YA==","signatures":[{"sig":"MEUCIQCAXihrWZpcvmgUTqPw7zF5yhiaNIX820FYnDMlxwjMvAIgaqN+Tv+a5Xov5Uz3UJCpuV3lGPlUBzwEn3Tvrl/fJrE=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":32833},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","gitHead":"c64acd206d7d56efbb063c60cd69b08337df1dfd","scripts":{"dev":"ts-node-esm ./src/index.ts","build":"tsc"},"_npmUser":{"name":"apexjs-org","email":"koen@kbim.nl"},"repository":{"url":"git+https://github.com/apexjs-org/openapi.git","type":"git"},"_npmVersion":"9.8.1","description":"An OpenAPI 3.1 description library for TypeScript with Zod schema support.","directories":{},"_nodeVersion":"18.18.0","dependencies":{"zod":"^3.24.4","zod-to-json-schema":"^3.24.5"},"_hasShrinkwrap":false,"devDependencies":{"ts-node":"^10.9.2","typescript":"^5.8.3","@types/node":"^22.15.17"},"_npmOperationalInternal":{"tmp":"tmp/openapi_1.0.0_1746734851749_0.6136465906045412","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@apexjs-org/openapi","version":"1.0.1","author":{"name":"apexjs-org"},"license":"MIT","_id":"@apexjs-org/openapi@1.0.1","maintainers":[{"name":"apexjs-org","email":"koen@kbim.nl"}],"homepage":"https://github.com/apexjs-org/openapi#readme","bugs":{"url":"https://github.com/apexjs-org/openapi/issues"},"dist":{"shasum":"4a8b5a18436c0df1f719647e688a09bf076a85b4","tarball":"https://registry.npmjs.org/@apexjs-org/openapi/-/openapi-1.0.1.tgz","fileCount":28,"integrity":"sha512-jmTtnG0quF6uMtunnokLR2C5C0mG4iHaD4BUfdo/nvEWCMD6nL7bQAUSks9RAhsmyENkzO/ceINHaac2JX+ycw==","signatures":[{"sig":"MEUCIFW3clO3o9kD4YCbOKyOy18KUH/5fy94Xt7q41bWxX4/AiEAhtVwdMmS1Yy9anNYs/qYdQs4nM2izcxqQRactn3Xlnw=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":32832},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","gitHead":"3e63544dfb4741a2a9117da0d2b41c266f5721e6","scripts":{"dev":"ts-node-esm ./src/index.ts","build":"tsc"},"_npmUser":{"name":"apexjs-org","email":"koen@kbim.nl"},"repository":{"url":"git+https://github.com/apexjs-org/openapi.git","type":"git"},"_npmVersion":"9.8.1","description":"An OpenAPI 3.1 description library for TypeScript with Zod schema support","directories":{},"_nodeVersion":"18.18.0","dependencies":{"zod":"^3.24.4","zod-to-json-schema":"^3.24.5"},"_hasShrinkwrap":false,"devDependencies":{"ts-node":"^10.9.2","typescript":"^5.8.3","@types/node":"^22.15.17"},"_npmOperationalInternal":{"tmp":"tmp/openapi_1.0.1_1746735029744_0.6723480245997582","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@apexjs-org/openapi","version":"1.0.2","author":{"name":"apexjs-org"},"license":"MIT","_id":"@apexjs-org/openapi@1.0.2","maintainers":[{"name":"apexjs-org","email":"koen@kbim.nl"}],"homepage":"https://github.com/apexjs-org/openapi#readme","bugs":{"url":"https://github.com/apexjs-org/openapi/issues"},"dist":{"shasum":"d5550affba089aff345cfab486261895c30df6b8","tarball":"https://registry.npmjs.org/@apexjs-org/openapi/-/openapi-1.0.2.tgz","fileCount":28,"integrity":"sha512-CjfhOf33NmzOzv9kklgoJzLgHdLJ9w/soT9v/2qSJTmCHq2ENdAGsJ8QaGWZEtomooI2nW93lJEhxleZUbhX3w==","signatures":[{"sig":"MEYCIQC2iPmge7y+w9oaVOGamn3S5RiFKD1itmdZtBSzYmJr0wIhAJxSGb3r8eIteL00/ICqMeUWBBgAhie33pUDPz3ktrVu","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":29440},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","gitHead":"0b34bdc7dc4540e1f61190fed31ce0fd87adb0ac","scripts":{"dev":"ts-node-esm ./src/index.ts","build":"tsc"},"_npmUser":{"name":"apexjs-org","email":"koen@kbim.nl"},"repository":{"url":"git+https://github.com/apexjs-org/openapi.git","type":"git"},"_npmVersion":"9.8.1","description":"An OpenAPI 3.1 description library for TypeScript with Zod schema support","directories":{},"_nodeVersion":"18.18.0","dependencies":{"zod":"^3.24.4","zod-to-json-schema":"^3.24.5"},"_hasShrinkwrap":false,"devDependencies":{"ts-node":"^10.9.2","typescript":"^5.8.3","@types/node":"^22.15.17"},"_npmOperationalInternal":{"tmp":"tmp/openapi_1.0.2_1746735842776_0.07204577791636901","host":"s3://npm-registry-packages-npm-production"}},"1.0.3":{"name":"@apexjs-org/openapi","version":"1.0.3","author":{"name":"apexjs-org"},"license":"MIT","_id":"@apexjs-org/openapi@1.0.3","maintainers":[{"name":"apexjs-org","email":"koen@kbim.nl"}],"homepage":"https://github.com/apexjs-org/openapi#readme","bugs":{"url":"https://github.com/apexjs-org/openapi/issues"},"dist":{"shasum":"e8bf5f9d0786064253dac66d17cc8e020cd2e5ec","tarball":"https://registry.npmjs.org/@apexjs-org/openapi/-/openapi-1.0.3.tgz","fileCount":34,"integrity":"sha512-3/pZ9m3jpgEE7EYDFrwaTsBdOQddk+hk7S2grG47g3wm/FR6gnvzC41k0EmObXp6jsSmiQoSVZQNFXylKm6XoA==","signatures":[{"sig":"MEYCIQCXhfqU7x7nxDi5BrXwT/TIqiFUIO4XRDdBHJZRkgSPkwIhANY62xTbwkKEJW+jRSrOXz1GiRoF9fBX8A+neWY9YDr1","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":35965},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","gitHead":"cb2720e6399b2a3e81c841346a540ecba779984e","scripts":{"dev":"ts-node-esm ./src/index.ts","build":"tsc"},"_npmUser":{"name":"apexjs-org","email":"koen@kbim.nl"},"repository":{"url":"git+https://github.com/apexjs-org/openapi.git","type":"git"},"_npmVersion":"9.8.1","description":"An OpenAPI 3.1 description library for TypeScript with Zod schema support","directories":{},"_nodeVersion":"18.18.0","dependencies":{"zod":"^3.24.4","zod-to-json-schema":"^3.24.5"},"_hasShrinkwrap":false,"devDependencies":{"ts-node":"^10.9.2","typescript":"^5.8.3","@types/node":"^22.15.17"},"_npmOperationalInternal":{"tmp":"tmp/openapi_1.0.3_1746780425647_0.7728631502933863","host":"s3://npm-registry-packages-npm-production"}},"1.0.4":{"name":"@apexjs-org/openapi","version":"1.0.4","description":"An OpenAPI 3.1 description library for TypeScript with Zod schema support","repository":{"type":"git","url":"git+https://github.com/apexjs-org/openapi.git"},"type":"module","main":"dist/index.js","scripts":{"build":"tsc","dev":"ts-node-esm ./src/index.ts"},"author":{"name":"apexjs-org"},"license":"MIT","devDependencies":{"@types/node":"^22.15.17","ts-node":"^10.9.2","typescript":"^5.8.3"},"dependencies":{"zod":"^3.24.4","zod-to-json-schema":"^3.24.5"},"_id":"@apexjs-org/openapi@1.0.4","gitHead":"1bff380a390dd145779007136bb2af3fdc2eabb2","types":"./dist/index.d.ts","bugs":{"url":"https://github.com/apexjs-org/openapi/issues"},"homepage":"https://github.com/apexjs-org/openapi#readme","_nodeVersion":"18.18.0","_npmVersion":"9.8.1","dist":{"integrity":"sha512-tLInafVKC/qk8C8NBnGYiwiwcZ6jK0NU2/NiBx3rcQEbMcfqlD5Lw8WrCSTjNgYFZT6M6ljQqKIRz1uAzF+gcw==","shasum":"1ff5e17d708479ed0afa13636791c3273f44beec","tarball":"https://registry.npmjs.org/@apexjs-org/openapi/-/openapi-1.0.4.tgz","fileCount":34,"unpackedSize":36463,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQClczEjmTgYgmEToS6T7zENrOxzpHolELuWHwmki/nL0QIhAJpLDbkI0K9TMffPvsGFMC1Sz/rQpcwhxIREy9JWTWD3"}]},"_npmUser":{"name":"apexjs-org","email":"koen@kbim.nl"},"directories":{},"maintainers":[{"name":"apexjs-org","email":"koen@kbim.nl"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/openapi_1.0.4_1746871334058_0.9454967531366822"},"_hasShrinkwrap":false}},"time":{"created":"2025-05-08T20:07:31.622Z","modified":"2025-05-10T10:02:14.442Z","1.0.0":"2025-05-08T20:07:31.973Z","1.0.1":"2025-05-08T20:10:29.918Z","1.0.2":"2025-05-08T20:24:02.971Z","1.0.3":"2025-05-09T08:47:05.819Z","1.0.4":"2025-05-10T10:02:14.258Z"},"bugs":{"url":"https://github.com/apexjs-org/openapi/issues"},"author":{"name":"apexjs-org"},"license":"MIT","homepage":"https://github.com/apexjs-org/openapi#readme","repository":{"type":"git","url":"git+https://github.com/apexjs-org/openapi.git"},"description":"An OpenAPI 3.1 description library for TypeScript with Zod schema support","maintainers":[{"name":"apexjs-org","email":"koen@kbim.nl"}],"readme":"# Easily create type-safe OpenAPI descriptions\n\n[@apexjs-org/openapi](https://www.npmjs.com/package/@apexjs-org/openapi) is an OpenAPI 3.1+ description library for TypeScript with Zod schema support. You can use this package to easily create a type-safe OpenAPI ([Swagger](https://swagger.io/docs/specification/v3_0/about/)) description. Use [express-openapi-validator](https://www.npmjs.com/package/express-openapi-validator) to bring your OpenAPI description to life with auto-validation and request handling. See the example folder or follow this [tutorial](https://medium.com/@apexjs-org/create-a-node-js-rest-api-with-an-openapi-description-in-minutes-972dda90e373).\n\n## Installation\n\n```sh\nnpm install @apexjs-org/openapi\n```\n\n## Example\n\nDefine your API response and request schemas as [Zod schemas](https://www.npmjs.com/package/zod) or [JSON schemas](https://json-schema.org/):\n```ts\n// schemas.ts\nimport { z } from \"zod\";\n\nexport const User = z.object({\n  id: z.string().regex(/^[a-zA-Z0-9-_]+$/).min(10).max(200),\n  email: z.string().email().min(5).max(200),\n  name: z.string().regex(/^[a-zA-Z0-9-_ ]+$/).min(2).max(200),\n  createdAt: z.optional(z.date()),\n});\n\nexport const UserList = z.object({\n  results: z.array(User),\n  totalCount: z.number()\n});\n\nexport const UserCreate = User.omit({ id: true, createdAt: true });\n\nexport const UserUpdate = User.pick({ name: true }).partial();\n```\n\nDefine your API paths as specified in the OpenAPI 3.1 specification with shorthands:\n\n```ts\n// paths.ts\nimport { type Paths, searchParameterRefs, jsonResponse, errorResponseRefs, jsonBody, idParameters, schemaRef } from \"@apexjs-org/openapi\";\n\nconst paths: Paths = {}\n\n// Methods for the /users path\npaths['/users'] = {\n  get: {\n    operationId: 'listUsers', // Name of the function that this request should trigger\n    summary: 'Finds users.',\n    parameters: searchParameterRefs(), // References the q, sort and offset parameters (included in components.parameters, see index.ts below)\n    responses: {\n      ...errorResponseRefs(), // References the BadRequest, Unauthorized, Forbidden, NotFound and TooManyRequests errors (included in components.responses, see index.ts below)\n      '200': jsonResponse(schemaRef('UserList')) // JSON response with a reference to a custom schema (included in components.schemas, see index.ts below)\n    }\n  },\n  post: {\n    operationId: 'createUser',\n    summary: 'Creates a new user.',\n    requestBody: jsonBody(schemaRef('UserCreate')), // JSON body with a reference to a custom schema (included in components.schemas, see index.ts below)\n    responses: {\n      ...errorResponseRefs(),\n      '201': jsonResponse(schemaRef('User'), 'created')\n    }\n  }\n};\n\n// Methods for the /users/{userId} path\npaths['/users/{userId}'] = {\n  get: {\n    operationId: 'getUser',\n    summary: 'Gets a user by id.',\n    parameters: idParameters(['userId']), // Specifies the userId parameter in this path\n    responses: {\n      ...errorResponseRefs(),\n      '200': jsonResponse(schemaRef('User'))\n    }\n  },\n  patch: {\n    operationId: 'updateUser',\n    summary: 'Updates a user by id.',\n    parameters: idParameters(['userId']),\n    requestBody: jsonBody(schemaRef('UserUpdate')),\n    responses: {\n      ...errorResponseRefs(),\n      '200': jsonResponse(schemaRef('User'))\n    }\n  },\n  delete: {\n    operationId: 'deleteUser',\n    summary: 'Deletes a user by id.',\n    parameters: idParameters(['userId']),\n    responses: {\n      ...errorResponseRefs(),\n      '200': jsonResponse() // JSON response without a schema (reference)\n    }\n  }\n};\n\nexport const userPaths = paths;\n```\n\nDefine your API as specified in the OpenAPI 3.1 specification. Use the schemas, paths and shorthands:\n\n```ts\n// index.ts\nimport { type OpenApi, bearerScheme, errorResponses, searchParameters, jsonSchemas, errorSchema } from \"@apexjs-org/openapi\";\nimport * as schemas from \"./schemas.js\";\nimport { userPaths } from \"./paths.js\";\n\nexport const openapi: OpenApi = {\n  openapi: '3.1.0',\n  info: {\n    title: 'API title',\n    version: '1.0.0'\n  },\n  security: [\n    { BearerAuth: [] } // Specifies that all paths should use the BearerAuth security scheme, see components.securitySchemes. Specifying security at the path method level is possible as well (to disable global security on path level, use: security: [])\n  ],\n  paths: userPaths,\n  components: {\n    schemas: {\n      Error: errorSchema(), // Specifies the Error schema for the error responses, same schema as express-openapi-validator errors\n      ...jsonSchemas(schemas) // Converts Zod schemas to JSON schemas\n    },\n    parameters: searchParameters(), // Specifies the q, sort and offset parameters so that they can be referenced\n    securitySchemes: {\n      BearerAuth: bearerScheme() // Specifies a bearer security scheme. openIdScheme() and oauth2Scheme() are possible as well\n    },\n    responses: errorResponses()\n  }\n}\n\n// console.dir(openapi, { depth: null })\n```\n\nYou can bring your OpenAPI description to life with [express-openapi-validator](https://github.com/cdimascio/express-openapi-validator). See the example folder or follow this [tutorial](https://dev.to/apexjs-org/create-a-nodejs-rest-api-with-an-openapi-description-in-minutes-2k73).","readmeFilename":"README.md"}