{"id":21301726,"url":"https://github.com/funbox/api-validator","last_synced_at":"2025-07-11T20:31:22.092Z","repository":{"id":40241713,"uuid":"460046381","full_name":"funbox/api-validator","owner":"funbox","description":"A tool to validate server responses using API Blueprint documentation","archived":false,"fork":false,"pushed_at":"2023-07-19T11:52:29.000Z","size":389,"stargazers_count":7,"open_issues_count":1,"forks_count":1,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-06-08T21:09:47.076Z","etag":null,"topics":["api-blueprint","apib","validation"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/funbox.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-02-16T14:46:56.000Z","updated_at":"2023-04-18T21:45:04.000Z","dependencies_parsed_at":"2023-02-08T12:16:32.603Z","dependency_job_id":null,"html_url":"https://github.com/funbox/api-validator","commit_stats":null,"previous_names":[],"tags_count":41,"template":false,"template_full_name":null,"purl":"pkg:github/funbox/api-validator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/funbox%2Fapi-validator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/funbox%2Fapi-validator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/funbox%2Fapi-validator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/funbox%2Fapi-validator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/funbox","download_url":"https://codeload.github.com/funbox/api-validator/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/funbox%2Fapi-validator/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264400370,"owners_count":23602243,"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":["api-blueprint","apib","validation"],"created_at":"2024-11-21T15:50:33.536Z","updated_at":"2025-07-11T20:31:17.071Z","avatar_url":"https://github.com/funbox.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @funboxteam/api-validator\n\n**api-validator** is a frontend tool to validate server response against API Blueprint documentation.\n\n[По-русски](./README.ru.md)\n\n## Rationale\n\nHaving human-readable documentation is a good way to specify a contract between client and server parts of an application.\nHowever, due to the complexity of modern web apps, a server response can contain dozens of fields and nested fields,\nand it is easy for backend to not comply with the documentation because of a bug or any other reason.\n\nTo minimize the number of errors on the frontend side associated with incorrect backend responses, we developed a tool\nfor automatic validation. It extracts JSON schema from the API Blueprint documentation and allows to automatically check\ncorrespondence between the backend response and the documentation for this request.\n\n## Installation\n\n```bash\nnpm install --save @funboxteam/api-validator\n```\n\n## Usage\n\n### Extracting of JSON schemas in frontend projects\n\nAdd the next `doc` field in`package.json`:\n  ```json\n  \"doc\": {\n    \"repo\": \"git@github.com:your-username/your-apib-repository.git\",\n    \"branch\": \"master\",\n    \"file\": \"doc.apib\"\n  }\n  ```\nwhere:\n  - `repo` — repository URL (required);\n  - `branch` — target branch name (required);\n  - `file` — file name in the repository (optional, default is `doc.apib`).\n   \nThis package exposes a binary called `update-schemas`, therefore you can generate schemas or update existing schemas\nby running `update-schemas` in a terminal.\n\nThis command will add required files in the project:\n   - `src/api-schemas/schemas.json` — contains schemas;\n   - `src/api-schemas/doc-version.txt` — contains the commit ID used to generate schemas.\n\n### Server response validation\n\nImport generated schemas from the project and the validation function from the package:\n\n```javascript\nimport { validateResponse } from '@funboxteam/api-validator';\nimport schemas from 'src/api-schemas/schemas';\n```\n\nCall the validation function with response parameters and generated schemas to get validation result:\n\n```javascript\nconst responseInfo = {\n  method: 'GET',\n  url: '/api/auth',\n  data: { status: 'ok' }\n};\n\nconst validationResult = validateResponse({\n  method: responseInfo.method,\n  url: responseInfo.url,\n  data: responseInfo.data,\n  schemas,\n});\n```\n\n## Examples\n\n### Example of validation in React projects\n\n```javascript\nimport axios from 'axios';\nimport settings from 'app/app.settings';\nimport schemas from 'api-schemas/schemas';\nimport { validateResponse, validationStatus } from '@funboxteam/api-validator';\n\naxios.interceptors.response.use(response =\u003e {\n  const result = validateResponse({\n    method: response.config.method,\n    url: response.config.url,\n    data: response.data,\n    schemas,\n    basePath: settings.apiBase,\n  });\n\n  switch (result.status) {\n    case validationStatus.invalid: {\n      console.log(`Validation error in ${response.config.method} ${response.config.url}`);\n      console.log(result);\n      return Promise.reject();\n    }\n\n    case validationStatus.schemaNotFound: {\n      console.log(`No schema for ${response.config.method} ${response.config.url}.`);\n      return Promise.reject();\n    }\n  }\n\n  return response;\n});\n```\n\n### Example of validation in Angular projects\n\n```javascript\nimport schemas from 'api-schemas/schemas';\nimport { validateResponse, validationStatus } from '@funboxteam/api-validator';\n\nangular.module('app').config(['restfulProvider', 'settings', (restfulProvider, settings) =\u003e {\n  restfulProvider.addInterceptor({\n    postProcessResponse: (respWrapper) =\u003e {\n      const response = respWrapper.response;\n\n      const result = validateResponse({\n        method: response.config.method,\n        url: response.config.url,\n        data: response.data,\n        schemas,\n        basePath: settings.apiBase,\n      });\n\n      switch (result.status) {\n        case validationStatus.invalid: {\n          console.log(`Validation error in ${response.config.method} ${response.config.url}`);\n          console.log(result);\n          respWrapper.isSuccessful = false;\n          break;\n        }\n\n        case validationStatus.schemaNotFound: {\n          console.log(`No schema for ${response.config.method} ${response.config.url}.`);\n          respWrapper.isSuccessful = false;\n          break;\n        }\n      }\n    },\n  });\n}]);\n```\n\n### Example of validation for WebSocket connections\n\nThis example is based on JavaScript client of the [Phoenix](https://hexdocs.pm/phoenix/js/) framework:\n\n```javascript\nimport schemas from 'api-schemas/schemas';\nimport { validateWebsocketResponse, validationStatus } from '@funboxteam/api-validator';\nconst { Socket } = require('phoenix');\n\nconst socket = new Socket('/adapter/v1', {});\n\nsocket.connect();\n\nconst channel = socket.channel('channel-topic');\n\nchannel.onMessage = (message, payload) =\u003e { // https://hexdocs.pm/phoenix/js/#channelonmessage\n  const result = validateWebsocketResponse({\n    messageTitle: message,\n    channel: channel.topic,\n    data: payload,\n    schemas,\n  });\n  switch (result.status) {\n    case validationStatus.valid:\n      console.log(`Schema of the message ${message} in the channel ${channel.topic} is valid`);\n      return payload;\n    case validationStatus.invalid:\n      console.warn(`Error during validation of the message ${message} in the channel ${channel.topic}`);\n      console.log(result);\n      return payload;\n    case validationStatus.schemaNotFound:\n      console.warn(`Schema of the message ${message} in the channel ${channel.topic} not found`);\n      return payload;\n    default:\n      return payload;\n  }\n};\n```\n\n[![Sponsored by FunBox](https://funbox.ru/badges/sponsored_by_funbox_centered.svg)](https://funbox.ru)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffunbox%2Fapi-validator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffunbox%2Fapi-validator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffunbox%2Fapi-validator/lists"}