{"id":15046244,"url":"https://github.com/skellla/fastify-oas","last_synced_at":"2025-04-07T17:10:43.634Z","repository":{"id":40294582,"uuid":"142213233","full_name":"SkeLLLa/fastify-oas","owner":"SkeLLLa","description":"Fastify OpenAPI plugin.","archived":false,"fork":false,"pushed_at":"2023-07-18T21:03:16.000Z","size":2095,"stargazers_count":73,"open_issues_count":44,"forks_count":20,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-31T16:14:36.324Z","etag":null,"topics":["fastify","fastify-plugin","openapi","openapi3","swagger"],"latest_commit_sha":null,"homepage":"https://www.comebackalive.in.ua/","language":"JavaScript","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/SkeLLLa.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","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}},"created_at":"2018-07-24T21:09:52.000Z","updated_at":"2025-03-16T00:16:44.000Z","dependencies_parsed_at":"2024-06-18T15:23:13.000Z","dependency_job_id":"6dc0f4c4-40e4-4776-a7e9-634cbb645e3b","html_url":"https://github.com/SkeLLLa/fastify-oas","commit_stats":null,"previous_names":[],"tags_count":70,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SkeLLLa%2Ffastify-oas","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SkeLLLa%2Ffastify-oas/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SkeLLLa%2Ffastify-oas/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SkeLLLa%2Ffastify-oas/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SkeLLLa","download_url":"https://codeload.github.com/SkeLLLa/fastify-oas/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247694876,"owners_count":20980733,"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","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":["fastify","fastify-plugin","openapi","openapi3","swagger"],"created_at":"2024-09-24T20:52:54.325Z","updated_at":"2025-04-07T17:10:43.614Z","avatar_url":"https://github.com/SkeLLLa.png","language":"JavaScript","readme":"# fastify-oas\n\n**NOTE**: OpenAPI 3 support finally [landed](https://github.com/fastify/fastify-swagger/pull/333) in \"official\" [fastify-swagger](https://github.com/fastify/fastify-swagger) module. Consider using it instead of this one, since it has better support for $ref in schemas.\n\nThis plugin is deprecated and no longer mainteined. Feel free to fork it and publish if needed.\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://gitlab.com/m03geek/fastify-oas/raw/master/logo.png\" alt=\"fastify-oas logo\"/\u003e\n\u003c/div\u003e\n\n[![NPM Version](https://img.shields.io/npm/v/fastify-oas.svg)](https://www.npmjs.com/package/fastify-oas)\n[![Downloads Count](https://img.shields.io/npm/dm/fastify-oas.svg)](https://www.npmjs.com/package/fastify-oas)\n[![Vunerabilities Count](https://snyk.io/test/npm/fastify-oas/badge.svg)](https://www.npmjs.com/package/fastify-oas)\n[![Build Status](https://gitlab.com/m03geek/fastify-oas/badges/master/pipeline.svg)](https://gitlab.com/m03geek/fastify-oas/commits/master)\n[![Coverage Status](https://gitlab.com/m03geek/fastify-oas/badges/master/coverage.svg)](https://gitlab.com/m03geek/fastify-oas/commits/master)\n[![License](https://img.shields.io/npm/l/fastify-oas.svg)](https://gitlab.com/m03geek/fastify-oas/blob/master/LICENSE)\n\n[OpenAPI 3.0+ (OAS3)](https://swagger.io/docs/specification/about/) documentation generator for Fastify.\nIt uses the schemas you declare in your routes to generate an OpenAPI (swagger) compliant doc.\n\nThis plugin based on [fastify-swagger](https://github.com/fastify/fastify-swagger/) that generates swagger 2.0 docs.\n\nThis plugin designed in such way to be compatible with it's predcessor and in most cases if you already use `fastify-swagger` you may just replace it with current plugin and it should work.\n\n## ToC\n- [fastify-oas](#fastify-oas)\n  - [ToC](#toc)\n  - [Fastify support](#fastify-support)\n  - [Installation](#installation)\n  - [Features and requirements](#features-and-requirements)\n  - [Usage](#usage)\n    - [Docs](#docs)\n    - [Plugin options](#plugin-options)\n    - [Additional schema options](#additional-schema-options)\n    - [OpenAPI](#openapi)\n    - [Swagger 2.0](#swagger-20)\n  - [UI](#ui)\n  - [Development](#development)\n  - [See also](#see-also)\n  - [License](#license)\n\n## Fastify support\n\n- v0.X.X - v1.X.X - supports fastify v1.X.X\n- v2.X.X - will support fastify v2.X.X*\n\n\u003cspan style=\"color:red; font-size:2em;\"\u003e\nCurrently in Fastify v2.12.0 there's regression bug that breakes this exenstion for many users. So for now this extension doesn't support fastify 2.12.0. Cause it was cause by fastify minor change in order to preven issues this library will throw an error when you'll try to use it with that fastify version.\nIn order to use it, you can either lock your fastify at 2.11.0 or fastify-oas at 2.5.0 (but there are no gaurantee that it will work correctly).\n\u003c/span\u003e\n\n\n## Installation\n\n```sh\nnpm i fastify-oas --save\n```\n\n\u003csub\u003e[Back to top](#toc)\u003c/sub\u003e\n\n## Features and requirements\n\n* Supports OpenAPI 3+.\n* Supports [fastify-swagger](https://github.com/fastify/fastify-swagger/) module configs.\n* Supports swagger 2.0 fastify schemas.\n* Supports fastify named schemas convertion to swaagger/openapi models.\n\n--- \n\n* Requires fastify `\u003e=1.9.0`.\n* Node.js `\u003e=8.9.0`.\n\nNOTE: If you need to generate fastify routes from your swagger document - please refer to plugins in [See also](#see-also) like fastify-swaggergen or fastify-openapi-glue.\n\n\u003csub\u003e[Back to top](#toc)\u003c/sub\u003e\n\n## Usage\n\nAdd it to your project like regular fastify plugin. Use `register` method and pass it swagger options, then call the api constructor.\n\n```js\nconst fastify = require('fastify');\nconst oas = require('fastify-oas');\nconst app = fastify();\n\napp.register(oas, {\n  routePrefix: '/documentation',\n  swagger: {\n    info: {\n      title: 'Test openapi',\n      description: 'testing the fastify swagger api',\n      version: '0.1.0',\n    },\n    externalDocs: {\n      url: 'https://swagger.io',\n      description: 'Find more info here',\n    },\n    consumes: ['application/json'],\n    produces: ['application/json'],\n  },\n  exposeRoute: true\n});\n\n// put some routes and schemas\n\napp.ready(err =\u003e {\n  if (err) throw err;\n  app.oas();\n});\n```\n\nPlease note, the schema format for Fastify routes is [JSONSchema](https://github.com/fastify/fastify/blob/v2.13.0/docs/Routes.md#routes-option) and you may encounter some differences in the format for route spec vs. output OpenAPI spec.  \nThis plugin includes handling around a few of these differences.\n\nOne such case is the `example` or `examples` keywords:\n```js\nfastify.route({\n  method: 'POST',\n  url: '/',\n  schema: {\n    body: {\n      type: 'object',\n      description: 'an object',\n      examples: [\n          {\n            name: 'Object Sample',\n            summary: 'an example',\n            value: {a: 'payload'},\n          }\n      ],\n      properties: {\n        a: {type: 'string', description: 'your payload'}\n      }\n    }\n  },\n  handler: // ...\n})\n```\nWhich produces a spec similar to:\n```json\n{\n  ... \n\n  \"content\": {\n    \"application/json\": {\n      \"examples\": {\n        \"Object Sample\": {\n          \"summary\": \"an example\",\n          \"value\": {\n            \"a\": \"payload\"\n          }\n        }\n      },\n      \"schema\": {\n        \"type\": \"object\",\n        \"properties\": {\n          \"a\": {\n            \"type\": \"string\",\n            \"description\": \"your payload\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n(in this case, the name property is extracted as the examples key)\n\n\u003csub\u003e[Back to top](#toc)\u003c/sub\u003e\n\n### Docs\n\nSee [Docs](/docs/README.md) for more details on the TypeScript types that you may use when working with OpenAPI spec.\n\n### Plugin options\n\n| parameter      | type    | description                                                                                                                                | default          |\n| -------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ---------------- |\n| `routePrefix`  | String  | Documentation endpoint                                                                                                                     | `/documentation` |\n| `exposeRoute`  | Boolean|Object** | If `true` the plugin will expose the documentation with the following apis: `/\u003croutePrefix\u003e`, `/\u003croutePrefix\u003e/json`, `/\u003croutePrefix\u003e/yaml` | `false`          |\n| `addModels`    | Boolean | If `true` adds fastify schemas as openapi models*                                                                                          | `false`          |\n| `openapi`      | String  | Openapi version                                                                                                                            | '3.0.0'          |\n| `yaml`         | Boolean | If `true` returns yaml instead of json                                                                                                     | `false`          |\n| `hideUntagged` | Boolean | If `true` remove routes without tags in schema from resulting swagger file                                                                 | `false`          |\n| `swagger`      | Object  | Swagger object except paths                                                                                                                | `{}`             |\n\nNote (*): Fastify-oas plugin gather all schemas, so you should ensure that all of them under current and nested scopes have unique names.\nNote (**): see [Expose route options](/docs/interfaces/fastifyoas.exposeoptions.md)\n\u003csub\u003e[Back to top](#toc)\u003c/sub\u003e\n\n### Additional schema options\n\nIn order to remove some endpoints from Swagger/OpenAPI document you may add `{hide: true}` option to route schema.\n\n```js\nconst fastify = require('fastify')()\nfastify.get('/some-secrete-route/:id', {\n  schema: {\n    hide: true,\n    params: {\n      type: 'object',\n      properties: {\n        id: {\n          type: 'string',\n          description: 'user id'\n        }\n      }\n    },\n    response: {\n      201: {\n        description: 'Successful response',\n        type: 'object',\n        properties: {\n          hello: { type: 'string' }\n        }\n      }\n    },\n  }\n}, (req, reply) =\u003e {})\n\n```\n\n\u003csub\u003e[Back to top](#toc)\u003c/sub\u003e\n\n### OpenAPI\n\nUnlike regular OpenAPI spec you'll still need some options from swagger 2.0.\n\n```js\nconst fastify = require('fastify');\nconst oas = require('fastify-oas');\nconst app = fastify();\n\napp.register(oas, {\n  routePrefix: '/documentation',\n  swagger: {\n    info: {\n      title: 'Test openapi',\n      description: 'testing the fastify swagger api',\n      version: '0.1.0',\n    },\n    externalDocs: {\n      url: 'https://swagger.io',\n      description: 'Find more info here',\n    },\n    consumes: ['application/json'], // app-wide default media-type\n    produces: ['application/json'], // app-wide default media-type\n    servers: [{\n      url: 'http://api.example.com/v1',\n      description: 'Optional server description, e.g. Main (production) server',\n    }],\n    components: {\n      // see https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md#componentsObject for more options\n      securitySchemes: {\n        BasicAuth: {\n          type: 'http',\n          scheme: 'basic',\n        },\n      },\n    }, \n  },\n});\n```\n\n\u003csub\u003e[Back to top](#toc)\u003c/sub\u003e\n\n### Swagger 2.0\n\nThis will not generate swagger 2.0 docs. It will generate openapi 3.0 docs, but from swagger 2.0 (and fastify-swagger) compatible configuration.\nIt will allow easily migrate from fastify-swagger.\n\nThe example below is taken from fastify-swagger repo to show the differences .\n\n```js\nconst fastify = require('fastify')()\n\n// before: fastify.register(require('fastify-swagger'), {\nfastify.register(require('fastify-oas'), { // after\n  routePrefix: '/documentation',\n  swagger: {\n    info: {\n      title: 'Test swagger',\n      description: 'testing the fastify swagger api',\n      version: '0.1.0'\n    },\n    externalDocs: {\n      url: 'https://swagger.io',\n      description: 'Find more info here'\n    },\n    host: 'localhost',\n    schemes: ['http'],\n    consumes: ['application/json'],\n    produces: ['application/json'],\n    tags: [\n      { name: 'user', description: 'User related end-points' },\n      { name: 'code', description: 'Code related end-points' }\n    ],\n    securityDefinitions: {\n      apiKey: {\n        type: 'apiKey',\n        name: 'apiKey',\n        in: 'header'\n      }\n    }\n  }\n})\n\nfastify.put('/some-route/:id', {\n  schema: {\n    description: 'post some data',\n    tags: ['user', 'code'],\n    summary: 'qwerty',\n    params: {\n      type: 'object',\n      properties: {\n        id: {\n          type: 'string',\n          description: 'user id'\n        }\n      }\n    },\n    body: {\n      type: 'object',\n      properties: {\n        hello: { type: 'string' },\n        obj: {\n          type: 'object',\n          properties: {\n            some: { type: 'string' }\n          }\n        }\n      }\n    },\n    response: {\n      201: {\n        description: 'Successful response',\n        type: 'object',\n        properties: {\n          hello: { type: 'string' }\n        }\n      }\n    },\n    security: [\n      {\n        \"api_key\": []\n      }\n    ]\n  }\n}, (req, reply) =\u003e {})\n\nfastify.ready(err =\u003e {\n  if (err) throw err\n  fastify.oas()\n})\n```\n\n\u003csub\u003e[Back to top](#toc)\u003c/sub\u003e\n\n## UI\n\nSwagger UI is available via `/\u003croutePrefix\u003e/index.html`. By default it's `/documentation/index.html`.\n\nReDoc UI is available via `/\u003croutePrefix\u003e/docs.html`. By default it's `/documentation/docs.html`.\n\n\u003csub\u003e[Back to top](#toc)\u003c/sub\u003e\n\n## Development\n\nIn order to start development run:\n\n```sh\nnpm i\nnpm run prepare\n```\n\nSo that [swagger-ui](https://github.com/swagger-api/swagger-ui) static folder will be generated for you.\n\n\u003csub\u003e[Back to top](#toc)\u003c/sub\u003e\n\n## See also\n\n* [fastify-swagger](https://github.com/fastify/fastify-swagger) - swagger 2.0 docs generation plugin.\n* [fastify-swaggergen](https://github.com/seriousme/fastify-swaggergen) - fastify routes generation from swagger 2.0 docs.\n* [fastify-openapi-glue](https://github.com/seriousme/fastify-openapi-glue) - fastify-swaggergen successor, generates fastify routes from swagger 2.0 and openapi 3.0 docs (just like this module, but in opposite direction).\n\n\u003csub\u003e[Back to top](#toc)\u003c/sub\u003e\n\n## License\n\nLicensed under [MIT](./LICENSE).\n\n\u003csub\u003e[Back to top](#toc)\u003c/sub\u003e\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fskellla%2Ffastify-oas","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fskellla%2Ffastify-oas","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fskellla%2Ffastify-oas/lists"}