{"id":15678973,"url":"https://github.com/ecyrbe/zodios-openapi","last_synced_at":"2025-08-20T02:32:16.692Z","repository":{"id":60934843,"uuid":"528361410","full_name":"ecyrbe/zodios-openapi","owner":"ecyrbe","description":"openapi description for zodios","archived":false,"fork":false,"pushed_at":"2025-08-19T13:56:47.000Z","size":784,"stargazers_count":17,"open_issues_count":11,"forks_count":5,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-08-19T15:39:01.564Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ecyrbe.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-08-24T09:52:58.000Z","updated_at":"2025-04-23T18:43:29.000Z","dependencies_parsed_at":"2023-12-27T01:33:35.570Z","dependency_job_id":"195cde8a-67b6-4882-a135-abae4f99ed21","html_url":"https://github.com/ecyrbe/zodios-openapi","commit_stats":{"total_commits":177,"total_committers":2,"mean_commits":88.5,"dds":"0.22033898305084743","last_synced_commit":"634a8da9bfc618b3831bbf33cac643ab780011c2"},"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"purl":"pkg:github/ecyrbe/zodios-openapi","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ecyrbe%2Fzodios-openapi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ecyrbe%2Fzodios-openapi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ecyrbe%2Fzodios-openapi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ecyrbe%2Fzodios-openapi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ecyrbe","download_url":"https://codeload.github.com/ecyrbe/zodios-openapi/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ecyrbe%2Fzodios-openapi/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271181472,"owners_count":24713107,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-19T02:00:09.176Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-03T16:25:44.278Z","updated_at":"2025-08-20T02:32:16.417Z","avatar_url":"https://github.com/ecyrbe.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":" \u003ch1 align=\"center\"\u003eZodios Openapi\u003c/h1\u003e\n \u003cp align=\"center\"\u003e\n   \u003ca href=\"https://github.com/ecyrbe/zodios-openapi\"\u003e\n     \u003cimg align=\"center\" src=\"https://raw.githubusercontent.com/ecyrbe/zodios-openapi/main/docs/logo.svg\" width=\"128px\" alt=\"Zodios logo\"\u003e\n   \u003c/a\u003e\n \u003c/p\u003e\n \u003cp align=\"center\"\u003e\n    Zodios Openapi is an openapi generator for zodios api description format.\n    \u003cbr/\u003e\n \u003c/p\u003e\n \n \u003cp align=\"center\"\u003e\n   \u003ca href=\"https://www.npmjs.com/package/@zodios/openapi\"\u003e\n   \u003cimg src=\"https://img.shields.io/npm/v/@zodios/openapi.svg\" alt=\"langue typescript\"\u003e\n   \u003c/a\u003e\n   \u003ca href=\"https://www.npmjs.com/package/@zodios/openapi\"\u003e\n   \u003cimg alt=\"npm\" src=\"https://img.shields.io/npm/dw/@zodios/openapi\"\u003e\n   \u003c/a\u003e\n   \u003ca href=\"https://github.com/ecyrbe/zodios-openapi/blob/main/LICENSE\"\u003e\n    \u003cimg alt=\"GitHub\" src=\"https://img.shields.io/github/license/ecyrbe/zodios-openapi\"\u003e   \n   \u003c/a\u003e\n   \u003cimg alt=\"GitHub Workflow Status\" src=\"https://img.shields.io/github/workflow/status/ecyrbe/zodios-openapi/CI\"\u003e\n \u003c/p\u003e\n\n# What is it ?\n\nIt's an openapi generator for zodios api description format.\n  \n- really simple centralized API declaration\n- generate openapi v3 json schema\n  \n**Table of contents:**\n\n- [What is it ?](#what-is-it-)\n- [Install](#install)\n- [How to use it ?](#how-to-use-it-)\n  - [Declare your API for fullstack end to end type safety](#declare-your-api-for-fullstack-end-to-end-type-safety)\n  - [Expose your OpenAPI documentation](#expose-your-openapi-documentation)\n\n# Install\n\n```bash\n\u003e npm install @zodios/openapi\n```\n\nor\n\n```bash\n\u003e yarn add @zodios/openapi\n```\n\n# How to use it ?\n\nOpenapi is a specification for describing REST APIs. It's a standard that is widely used in the industry. It's a great way to document your API and zodios-openapi is a tool to generate openapi v3 json schema from zodios api description format.\n\n## Declare your API for fullstack end to end type safety\n\nHere is an example of API declaration with Zodios. Splitted between public and admin API.\n  \nin a common directory (ex: `src/api.ts`) :\n\n```typescript\nimport { makeApi } from \"@zodios/core\";\nimport { z } from \"zod\";\n\nexport const userApi = makeApi([\n  {\n    method: \"get\",\n    path: \"/users\",\n    alias: \"getUsers\",\n    description: \"Get all users\",\n    parameters: [\n      {\n        name: \"limit\",\n        type: \"Query\",\n        description: \"Limit the number of users\",\n        schema: z.number().positive(),\n      },\n      {\n        name: \"offset\",\n        type: \"Query\",\n        description: \"Offset the number of users\",\n        schema: z.number().positive().optional(),\n      },\n    ],\n    response: z.array(userSchema),\n    errors,\n  },\n  {\n    method: \"get\",\n    path: \"/users/:id\",\n    alias: \"getUser\",\n    description: \"Get a user by id\",\n    response: userSchema,\n    errors,\n  },\n  {\n    method: \"get\",\n    path: \"/users/:id/comments\",\n    alias: \"getComments\",\n    description: \"Get all user comments\",\n    response: z.array(commentSchema),\n    errors,\n  },\n  {\n    method: \"get\",\n    path: \"/users/:id/comments/:commentId\",\n    alias: \"getComment\",\n    description: \"Get a user comment by id\",\n    response: commentSchema,\n    errors,\n  },\n]);\n\nexport const adminApi = makeApi([\n  {\n    method: \"post\",\n    path: \"/users\",\n    alias: \"createUser\",\n    description: \"Create a user\",\n    parameters: [\n      {\n        name: \"user\",\n        type: \"Body\",\n        description: \"The user to create\",\n        schema: userSchema.omit({ id: true }),\n      },\n    ],\n    response: userSchema,\n    errors,\n  },\n  {\n    method: \"put\",\n    path: \"/users/:id\",\n    alias: \"updateUser\",\n    description: \"Update a user\",\n    parameters: [\n      {\n        name: \"user\",\n        type: \"Body\",\n        description: \"The user to update\",\n        schema: userSchema,\n      },\n    ],\n    response: userSchema,\n    errors,\n  },\n  {\n    method: \"delete\",\n    path: \"/users/:id\",\n    alias: \"deleteUser\",\n    description: \"Delete a user\",\n    response: z.void(),\n    status: 204,\n    errors,\n  },\n]);\n```\n\n## Expose your OpenAPI documentation\n\n\nin your backend (ex: `src/server.ts`) :\n```typescript\nimport { serve, setup } from \"swagger-ui-express\";\nimport { makeApi } from \"@zodios/core\";\nimport { zodiosApp, zodiosRouter } from \"@zodios/express\";\nimport { bearerAuthScheme, openApiBuilder } from \"@zodios/openapi\";\nimport { userApi, adminApi } from \"./api\";\n\nconst app = zodiosApp();\nconst userRouter = zodiosRouter([...userApi, ...adminApi]);\n\n\napp.use(\"/api/v1\", userRouter);\n\nconst document = openApiBuilder({\n  title: \"User API\",\n  version: \"1.0.0\",\n  description: \"A simple user API\",\n})\n  .addServer({ url: \"/api/v1\" })\n  .addSecurityScheme(\"admin\", bearerAuthScheme())\n  .addPublicApi(api)\n  .addProtectedApi(\"admin\", adminApi)\n  .build();\n\napp.use(`/docs/swagger.json`, (_, res) =\u003e res.json(document));\napp.use(\"/docs\", serve);\napp.use(\"/docs\", setup(undefined, { swaggerUrl: \"/docs/swagger.json\" }));\n\napp.listen(3000);\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fecyrbe%2Fzodios-openapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fecyrbe%2Fzodios-openapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fecyrbe%2Fzodios-openapi/lists"}