{"id":18763227,"url":"https://github.com/ajaxy/tinyspec","last_synced_at":"2025-08-27T11:18:12.979Z","repository":{"id":17070584,"uuid":"80019801","full_name":"Ajaxy/tinyspec","owner":"Ajaxy","description":"Simple syntax for describing REST APIs","archived":false,"fork":false,"pushed_at":"2023-01-07T03:58:40.000Z","size":781,"stargazers_count":102,"open_issues_count":7,"forks_count":15,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-08-10T20:40:03.950Z","etag":null,"topics":["api","documentation","documentation-tool","openapi","rest","rest-api","restful","restful-api","specification","swagger"],"latest_commit_sha":null,"homepage":"https://ajaxy.github.io/tinyspec","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/Ajaxy.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":"2017-01-25T14:04:07.000Z","updated_at":"2024-11-22T14:53:30.000Z","dependencies_parsed_at":"2023-01-13T19:08:50.744Z","dependency_job_id":null,"html_url":"https://github.com/Ajaxy/tinyspec","commit_stats":null,"previous_names":[],"tags_count":72,"template":false,"template_full_name":null,"purl":"pkg:github/Ajaxy/tinyspec","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ajaxy%2Ftinyspec","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ajaxy%2Ftinyspec/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ajaxy%2Ftinyspec/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ajaxy%2Ftinyspec/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Ajaxy","download_url":"https://codeload.github.com/Ajaxy/tinyspec/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ajaxy%2Ftinyspec/sbom","scorecard":{"id":9750,"data":{"date":"2025-08-11","repo":{"name":"github.com/Ajaxy/tinyspec","commit":"9b7b356de02c96fe99fe007e02f9081755efe51f"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":1.9,"checks":[{"name":"Token-Permissions","score":-1,"reason":"No tokens found","details":null,"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"Maintained","score":0,"reason":"0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Dangerous-Workflow","score":-1,"reason":"no workflows found","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Code-Review","score":1,"reason":"Found 3/18 approved changesets -- score normalized to 1","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"Pinned-Dependencies","score":-1,"reason":"no dependencies found","details":null,"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: MIT License: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":0,"reason":"branch protection not enabled on development/release branches","details":["Warn: branch protection not enabled for branch 'master'"],"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 0 commits out of 15 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}},{"name":"Vulnerabilities","score":0,"reason":"18 existing vulnerabilities detected","details":["Warn: Project is vulnerable to: GHSA-968p-4wvh-cqc8","Warn: Project is vulnerable to: GHSA-67hx-6x53-jw92","Warn: Project is vulnerable to: GHSA-93q8-gq69-wqmw","Warn: Project is vulnerable to: GHSA-v6h2-p8h4-qcjw","Warn: Project is vulnerable to: GHSA-grv7-fg5c-xmjg","Warn: Project is vulnerable to: GHSA-3xgq-45jj-v275","Warn: Project is vulnerable to: GHSA-fjxv-7rqg-78g4","Warn: Project is vulnerable to: GHSA-9c47-m6qq-7p4h","Warn: Project is vulnerable to: GHSA-952p-6rrq-rcjv","Warn: Project is vulnerable to: GHSA-f8q6-p94x-37v3","Warn: Project is vulnerable to: GHSA-xvch-5gv4-984h","Warn: Project is vulnerable to: GHSA-c2qf-rxjj-qqgw","Warn: Project is vulnerable to: GHSA-jgrx-mgxx-jf9v","Warn: Project is vulnerable to: GHSA-72xf-g2v4-qvf3","Warn: Project is vulnerable to: GHSA-qgmg-gppg-76g5","Warn: Project is vulnerable to: GHSA-xx4c-jj58-r7x6","Warn: Project is vulnerable to: GHSA-j8xg-fqg3-53r7","Warn: Project is vulnerable to: GHSA-3h5v-q93c-6h6q"],"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}}]},"last_synced_at":"2025-08-14T14:19:02.982Z","repository_id":17070584,"created_at":"2025-08-14T14:19:02.982Z","updated_at":"2025-08-14T14:19:02.982Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272325406,"owners_count":24914642,"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-27T02:00:09.397Z","response_time":76,"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":["api","documentation","documentation-tool","openapi","rest","rest-api","restful","restful-api","specification","swagger"],"created_at":"2024-11-07T18:25:24.728Z","updated_at":"2025-08-27T11:18:12.954Z","avatar_url":"https://github.com/Ajaxy.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":":mega: Read an article about [Specification-driven development](https://www.toptal.com/api-developers/5-new-things-rest-specification) of REST APIs.\n\n:cloud: Deploy your OpenAPI spec to [Tinyspec Cloud Beta](https://github.com/Ajaxy/tinyspec-cloud) to generate and host beautiful REST API documentation.\n\n# \u003cimg src=\"docs/logo.png\" width=\"165\" title=\"tinyspec\" alt=\"tinyspec\" /\u003e\n\n[![NPM version](https://img.shields.io/npm/v/tinyspec.svg)](https://npmjs.com/package/tinyspec)\n\n- [About](#about)\n- [Installing](#installing)\n- [Quick Start and Demo](#quick-start-and-demo)\n- [Tinyspec Syntax](#tinyspec-syntax)\n    - [Models Definition](#models-definition)\n    - [Endpoints Definition](#endpoints-paths-definition)\n    - [API General Information](#api-general-information)\n    - [Comments](#comments)\n- [Generating Documentation](#generating-documentation)\n    - [Using With GitHub Pages](#generating-documentation-for-existing-projects-with-support-of-github-pages)\n    - [Using With Asciidoctor](#using-with-asciidoctor)\n    - [Tinyspec Cloud](#tinyspec-cloud)\n- [OpenAPI version](#openapi-version)\n- [Contributing](#contributing)\n\n## About\n\nTinyspec offers a lightweight and human-readable alternative to the more verbose [OpenAPI/Swagger](https://github.com/OAI/OpenAPI-Specification) format. It relies on the strengths of the OpenAPI format without the need to maintain the single large JSON or YAML file or to use some special software, instead allowing you to keep your API endpoints and models in separate and easy to maintain files.\n\nPossible outputs include a full OpenAPI specification in YAML and JSON formats, or the API documentation in HTML format created with the help of the [bootprint-openapi](https://github.com/bootprint/bootprint-openapi).\n\n\n## Installing\nTo use `tinyspec`, install it globally. Use [npm](https://www.npmjs.com/) for it:\n```\nnpm install -g tinyspec\n```\n\nFor vscode users, install our vscode extension\n\n[https://marketplace.visualstudio.com/items?itemName=frolovdev.tinyspec-lang](https://marketplace.visualstudio.com/items?itemName=frolovdev.tinyspec-lang)\n\n## Quick Start and Demo\nTo generate the API documentation, follow these steps:\n\n1. Create [`models.tinyspec`](examples/models.tinyspec), [`endpoints.tinyspec`](examples/endpoints.tinyspec) and [`header.yaml`](examples/header.yaml) files. You can find more information on how to write these files yourself below.\n2. Run `tinyspec -h`.\n\nYou documentation is generated! Check out this [**DEMO**](https://ajaxy.github.io/tinyspec) to see how it may look like.\n\n## Tinyspec Syntax\nTinyspec definition is split into 3 different sections. You specify models and endpoints that the API uses in the special tinyspec format and place any extra information in the `header.yaml` file.\n\n### Models Definition\nModels (_definitions_) are described in `models.tinyspec` files. You can also split model definitions in multiple `*.models.tinyspec` files and even place them in folders to make the API specification easier to maintain.\n\nThe basic model looks like this:\n```\nMyModel {field1, field2}\n```\nYou can describe any number of models in a single `*.models.tinyspec` file. Fields should be separated by `,`. By default, all fields are required and accept `string` data values. \nBut if you need a colon in the field name, you should specify the type explicitly.\n\n#### Data Types\nTo specify the expected data type, add it after semicolon (`:`). To make fields accept arrays, add brackets (`[]`). For example to define an object:\n```\nMyModel {field1: b, field2: float[]}\n```\nYou can use the full type name (`string`, `integer`, `boolean`, etc) or a shorthand (`s`, `i`, `b` and so on). Possible values:\n\nShorthand|Full|OpenAPI type|OpenAPI format|\n---------|----|------------|--------------|\n`i`| `integer`\n`s`| `string`\n`b`| `boolean`\n`o`| `object`\n`f`| `float` | `number`\n(none) | `date` | `string` | `date`\n`d`| `datetime` | `string` | `date-time`\n`t`| `text` | `string`\n`j`| `json` | `string`\n\n#### Enum\nYou can describe a fixed list of possible values separated by `|` within parentheses `()`.\n```\nMyModel {color: (sample|42|true)}\n```\n\n#### References to Other Models\nYou can reference other models:\n```\nDimensions {width: i, height: i}\nColor (red|green|blue)\nMyModel {dimensions: Dimensions, color: Color}\n```\n\n#### Optional Fields\nTo mark the field as optional, add a question mark (`?`) after the field name, for example:\n```\nMyModel {field1?, field2?: b}\n```\n#### Strict Definition Adherence\nBy default, objects may contain extra fields that are not specified in the model. If you need a strict adherence to the schema, add an exclamation mark (`!`) before the definitions, for example:\n```\nMyModel !{field1, field2}\n```\nThis is a representation of OpenAPI `additionalProperties: false`.\n\n#### Reusing Previously Defined Model\nYou can reuse the defined model object and create a new one as needed. Use the less-than sign (`\u003c`) to reuse the object.\nWhen you reuse the object, you can remove a part of its definition. To do this, add a minus sign before the field (`-`).\nYou can also add additional fields as needed. Here is how you can do this:\n```\nMyModel {field1, field2}\nMyOtherModel \u003c MyModel {-field2, field3}\n```\nAs a result, `MyOtherModel` will have `field1` and `field3` values, but `field2` will be excluded.\n\n#### Multi-line Models\nYour models may be multi-line:\n```\nMyModel {\n    field1,\n    field2: b\n}\n```\n\n#### Models Description\nTo create a description for the model, add a text line prefixed with `//` before its definition. Description may be multi-line and supports Markdown. Here is how it looks like:\n```\n// My _perfect_ tiny model\nMyModed {field}\n```\n\n### Endpoints (Paths) Definition\nEndpoints (_paths_) are described in `endpoints.tinyspec` files. As with models definitions, you can split endpoint definitions into multiple `*.endpoints.tinyspec` files or place them in folders to make the specification easier to maintain.\n\nThe basic endpoint definition looks like this:\n```\nPOST /resources {key: Model}\n    =\u003e {success: b, error: b}\nGET /resources\n    =\u003e {key: Model[]}\n```\n\nYou can expand it in the following ways:\n\n#### Parameters and Responses\nRequest _body parameters_ are specified using `{...}` right after the resource name (see example above).\n\nTo specify _query parameters_, add the question mark (`?`) after the path and list the query parameters.\nYou can add multiple parameters by connecting them with the ampersand symbol (`\u0026`).\n\n_Responses_ are specified below the endpoint definitions prefixed with an indent and `=\u003e` sign. You can specify status before the response definition, otherwise the status `200` is used by default.\nYou can also provide a response description using a text line prefixed with `//`.\n\nParameters and responses definition format is the same as for models. For example, you can refer to other models, make some parameters optional or specify the required data type:\n```\nGET /examples?sort\u0026limit?:i\n    =\u003e {examples: Example[], totalCount?: i}\n    // Response description\n    =\u003e 404 NotFoundError\n```\n\n#### Endpoints Description\nTo create a description for the endpoint, add a text line prefixed with `//` before its definition. Description may be multi-line and supports Markdown. Here is how it looks like:\n```\n// Get **ALL** objects.\nGET /examples\n    =\u003e {examples: Example[]}\n```\n\n#### Automatic Generation of Basic Methods\nYou can quickly create CRUDL actions (_create_, _retrieve_, _update_, _delete_, _list_) for a specified resources by using a dollar sign (`$`) followed by actions abbreviation (i.e. `$CRUDL`) in place of the request method. For example:\n\n```\n$CRUDL /examples\n```\nThis tiny piece would be an equivalent to:\n```\n// **List** _examples_\nGET /examples\n    =\u003e {examples: Example[]}\n\n// **Create** new _example_\nPOST /examples {example: ExampleNew}\n    =\u003e 201 {example: Example}\n\n// **Retrieve** _example_\nGET /examples/:id\n    =\u003e {example: Example}\n\n// **Update** _example_\nPATCH /examples/:id {example: ExampleUpdate}\n    =\u003e {example: Example}\n\n// **Delete** _example_\nDELETE /examples/:id\n    =\u003e {success: b}\n```\n\nIf you only need some methods, omit the key you do not need (for example `$RD` will only create _retrieve_ and _delete_ actions).\n\nBy default the last _path_ member is used to produce model name and payload keys (see above).\nAlternatively, you can specify your own key and model name. You can also add postfix `$` to the model name to append `*New` and `*Update` postfixes in generated endpoints:\n```\n$CRUDL /examples {myKey: MyModel$}\n```\n\n#### Authorization\nIf your API uses authorization, describe the authorization method in the `headers.yaml` file and then address it before the endpoint definition by using the \"at\" sign (`@`). For example:\n```\n// header.yaml\nsecurityDefinitions:\n  auth:\n    name: X-Access-Token\n    type: apiKey\n    in: header\n\n// examples.endpoints.tinyspec\n@auth GET /examples\n    =\u003e {examples: MyModel}\n```\n\n#### Endpoint Tags\nTags let you group endpoints by the parameter you need. For example you can group your endpoints by your API client type or role.\nTo create a tag, add it with semicolon (`:`) before the definition. For example, to create the `Admin` endpoints group:\n```\nAdmin:\n    GET /users\n        =\u003e {users: User[]}\n```\nTags are consistent across all endpoint definition files.\n\n**Note:** OpenAPI requires unique `METHOD /URLs` for each endpoint specified. To make endpoints separated by tags unique, add the group name in brackets:\n```\nGuest endpoints:\n    GET /articles (guest)\n        =\u003e {articles: Article[]}\n\nAdmin endpoints:\n    GET /articles (admin)?filter\u0026sort\u0026limit:i\n        =\u003e {articles: Article[], totalCount: i}\n```\n\n### API General Information\nFor any API information other than API endpoints and models you use the `header.yaml` file. The file should be written in regular OpenAPI format.\n\n### Comments\nYou can add one-line comments prefixed with symbol `#` in any place. Comments will be ignored during parsing.\n\n## Generating Documentation\nTo generate OpenAPI or HTML specification from tinyspec format, run it with one of the available options:\n```\ntinyspec [option]\n\nOptions:\n    --yaml | -y     Generate OpenAPI/Swagger YAML\n    --json | -j     Generate OpenAPI/Swagger JSON\n    --html | -h     Generate HTML/CSS document\n    --src | -s      Path to sources directory, defaults to current directory\n    --output | -o   Path to place generated files\n    --add-nulls     Include `null` as possible value for non-required fields\n    --help          Display this help\n```\n\n### Generating Documentation for Existing Projects With Support of GitHub Pages\nTo generate the documentation for GitHub pages from the existing project:\n\n* Install tinyspec locally: `npm install --save-dev tinyspec`.\n* Create your `*.tinyspec` definitions and `header.yaml`.\n* Edit `package.json` to prepare the documentation for GitHub Pages:\n```json\n  \"scripts\": {\n    \"docs\": \"tinyspec -h -o ../docs/\"\n  }\n```\n* Execute the `npm run docs` command, commit and push changes and check out your GitHub static website.\n\nFor more information about GitHub Pages, [see this article](https://help.github.com/articles/configuring-a-publishing-source-for-github-pages/).\n\n### Using With Asciidoctor\nCheck out [this repo](https://github.com/Ajaxy/openapi-asciidoctor) to produce even more beautiful HTML (and PDF) output.\n\n### Tinyspec Cloud\n[Tinyspec Cloud](https://tinyspec.cloud) is a documentation hosting service with a themes marketplace launching soon.\n\n### Tinyspec vscode\n[Tinyspec vscode](https://github.com/frolovdev/vscode-tinyspec) is a vscode extension that enhance your developer experience.\n\n## OpenAPI version\nThe current version of tinyspec produces Swagger/OpenAPI 2.0. The new 3.0 version has got some nice features there, but is not well supported by most third-party tools yet. The compatibility with OpenAPI 3.0 is to be added in future.\n\n## Contributing\nContributions and feedback are always welcome. If you have an idea on how to make tinyspec better, feel free to create an issue and/or pull request.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fajaxy%2Ftinyspec","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fajaxy%2Ftinyspec","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fajaxy%2Ftinyspec/lists"}