{"id":22799992,"url":"https://github.com/dadi/apidoc","last_synced_at":"2025-07-28T14:09:01.004Z","repository":{"id":57105375,"uuid":"49805881","full_name":"dadi/apidoc","owner":"dadi","description":"API documentation middleware for DADI API","archived":false,"fork":false,"pushed_at":"2019-05-16T09:41:51.000Z","size":931,"stargazers_count":3,"open_issues_count":8,"forks_count":2,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-06-24T21:43:18.710Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dadi.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-01-17T06:25:36.000Z","updated_at":"2018-10-19T12:35:04.000Z","dependencies_parsed_at":"2022-08-20T23:50:09.819Z","dependency_job_id":null,"html_url":"https://github.com/dadi/apidoc","commit_stats":null,"previous_names":["dadi/api-doc"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/dadi/apidoc","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dadi%2Fapidoc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dadi%2Fapidoc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dadi%2Fapidoc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dadi%2Fapidoc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dadi","download_url":"https://codeload.github.com/dadi/apidoc/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dadi%2Fapidoc/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267527835,"owners_count":24102019,"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-07-28T02:00:09.689Z","response_time":68,"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-12-12T07:10:43.660Z","updated_at":"2025-07-28T14:09:00.975Z","avatar_url":"https://github.com/dadi.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DADI API Documentation\n\n[![npm (scoped)](https://img.shields.io/npm/v/@dadi/apidoc.svg?maxAge=10800\u0026style=flat-square)](https://www.npmjs.com/package/@dadi/apidoc)\n[![JavaScript Style Guide](https://img.shields.io/badge/code%20style-standard-brightgreen.svg?style=flat-square)](http://standardjs.com/)\n\n\u003e API documentation middleware for DADI API\n\n* [Introduction](#introduction)\n* [Installation](#installation)\n* [Generating Code Snippets](#generating-code-snippets)\n* [Documenting custom endpoints](#documenting-custom-endpoints)\n* [Showing useful example values](#showing-useful-example-values)\n* [Excluding Collections, Endpoints and Fields](#excluding-collections-endpoints-and-fields)\n\n## Introduction\n\nThis package provides a set of auto-generated documentation for your API installation, reading information from the collection schemas and custom endpoints to describe the available HTTP methods and parameters required to interact with the API.\n\n##### A guide to acquiring an access token\n![Authentication](templates/authentication.png)\n\n##### Describing a GET request for the User collection\n![GET Request](templates/get.png)\n\n##### Describing a POST request for the User collection\n![POST Request](templates/post.png)\n\n\n## Installation\n\n```shell\n$ npm install @dadi/apidoc --save\n```\n\n#### Add an `apidoc` section to the API's configuration file\n\n```js\n\"apidoc\": {\n  \"title\": \"\u003cProject Name\u003e Content API\",\n  \"description\": \"This is the _Content API_ for [Example](http://www.example.com).\",\n  \"markdown\": false,\n  \"path\": \"docs\",\n  \"generateCodeSnippets\": false,\n  \"themeVariables\": \"default\",\n  \"themeTemplate\": \"triple\",\n  \"themeStyle\": \"default\",\n  \"themeCondenseNav\":\ttrue,\n  \"themeFullWidth\": false\n}\n```\n\n#### Initialise the middleware\n\nThis example shows API Doc being initialised in the installed API's entry point, the `main.js` file,\nafter the server has started.\n\n```js\nvar server = require('@dadi/api')\nvar config = require('@dadi/api').Config\nvar log = require('@dadi/api').Log\n\nserver.start(function() {\n  log.get().info('API Started')\n})\n\n// add documentation route\nrequire('@dadi/apidoc').init(server, config)\n```\n\n#### Browse the documentation\n\nBy default the documentation can be browsed using the route `/api/1.0/docs`.\n\nFor example of your API is running at `http://api.example.com` then your documentation is available at `http://api.example.com/api/1.0/docs`.\n\n## Generating Code Snippets\n\nIf you want to generate code snippets (made possible by the configuration option\n  `generateCodeSnippets`) you'll need to ensure sure your system has the following:\n\n1) Ruby, and the Ruby gem `awesome_print`:\n\n```shell\n$ gem install awesome_print\n```\n\n2) The `httpsnippet` package:\n\n```shell\n$ npm install httpsnippet --global\n```\n\n## Documenting custom endpoints\n\nAPI collections are automatically documented using values from with the collection schema files. To have your documentation include useful information about custom endpoints, add [JSDoc](http://usejsdoc.org/) comments to the endpoint files:\n\n```js\n/**\n * Adds two numbers together.\n *\n * ```js\n * var result = add(1, 2);\n * ```\n *\n * @param {int} `num1` The first number.\n * @param {int} `num2` The second number.\n * @returns {int} The sum of the two numbers.\n * @api public\n */\n```\n\n## Showing useful example values\n\nTo show example data in the documentation that isn't simply the default of \"Hello World!\",\nyou can add properties to fields in the API collection schema.\n\n### `example`\n\nThe `example` property is a static value that will be the same every time you view the documentation.\n\n```js\n\"platform\": {\n  \"type\": \"String\",\n  \"required\": true,\n  \"example\": \"twitter\",\n  \"validation\": {\n    \"regex\": {\n      \"pattern\": \"twitter|facebook|instagram\"\n    }\n  }\n}\n```\n\n### `testDataFormat`\n\nThe `testDataFormat` property allows you to specify any type from the [faker](https://github.com/FotoVerite/Faker.js) package, which will insert\na random value of the selected type each time the documentation is viewed:\n\n```js\n\"email\": {\n  \"type\": \"String\",\n  \"required\": true,\n  \"validation\": {\n    \"regex\": {\n      \"pattern\": \".+@.+\"\n    }\n  },\n  \"testDataFormat\": \"{{internet.email}}\"\n}\n```\n\nSee a list of available options [here](https://github.com/FotoVerite/Faker.js).\n\n\n## Excluding Collections, Endpoints and Fields\n\nOften an API build contains collections and collection fields that are meant for\ninternal use and including them in the API documentation is undersirable.\n\nTo exclude collections and fields from your generated documentation, see the following\nsections.\n\n### Excluding Collections\n\nAdd a `private` property to the collection specification's `settings` section:\n\n```js\n{\n  \"fields\": {\n    \"title\": {\n      \"type\": \"String\",\n      \"required\": true\n    },\n    \"author\": {\n      \"type\": \"Reference\",\n      \"settings\": {\n        \"collection\": \"people\"\n      }\n    }\n  },\n  \"settings\": {\n    \"cache\": true,\n    \"count\": 40,\n    \"sort\": \"title\",\n    \"sortOrder\": 1,\n    \"private\": true\n  }\n}\n```\n\n### Excluding Endpoints\n\nAdd a `private` property to the endpoint file's `model.settings` section:\n\n```js\nmodule.exports.get = function (req, res, next) {\n  res.setHeader('content-type', 'application/json')\n  res.statusCode = 200\n  res.end(JSON.stringify({message: 'Hello World'}))\n}\n\nmodule.exports.model = {\n  \"settings\": {\n    \"cache\": true,\n    \"authenticate\": false,\n    \"private\": true\n  }\n}\n```\n\n### Excluding Fields\n\nAdd a `private` property to the field specification:\n\n```js\n{\n  \"fields\": {\n    \"title\": {\n      \"type\": \"String\",\n      \"required\": true\n    },\n    \"internalId\": {\n      \"type\": \"Number\",\n      \"required\": true,\n      \"private\": true\n    }\n  },\n  \"settings\": {\n    \"cache\": true,\n    \"count\": 40,\n    \"sort\": \"title\",\n    \"sortOrder\": 1\n  }\n}\n```\n\n## Roadmap\n\n* Template customisation\n\n## Licence\n\nDADI is a data centric development and delivery stack, built specifically in support of the principles of API first and COPE.\n\nCopyright notice\n(C) 2016 DADI+ Limited \u003csupport@dadi.tech\u003e\nAll rights reserved\n\nThis product is part of DADI.\nDADI is free software; you can redistribute it and/or modify\nit under the terms of the GNU General Public License as\npublished by the Free Software Foundation; either version 2 of\nthe License, or (at your option) any later version (\"the GPL\").\n**If you wish to use DADI outside the scope of the GPL, please\ncontact us at info@dadi.co for details of alternative licence\narrangements.**\n\n**This product may be distributed alongside other components\navailable under different licences (which may not be GPL). See\nthose components themselves, or the documentation accompanying\nthem, to determine what licences are applicable.**\n\nDADI is distributed in the hope that it will be useful,\nbut WITHOUT ANY WARRANTY; without even the implied warranty of\nMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\nGNU General Public License for more details.\n\nThe GNU General Public License (GPL) is available at\nhttp://www.gnu.org/copyleft/gpl.html.\nA copy can be found in the file GPL distributed with\nthese files.\n\nThis copyright notice MUST APPEAR in all copies of the product!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdadi%2Fapidoc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdadi%2Fapidoc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdadi%2Fapidoc/lists"}