Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/sina-byn/auto-api-dog
a Node.JS CLI tool to easily generate api dog documentation file from your comments
https://github.com/sina-byn/auto-api-dog
api api-doc api-docs api-document-generation api-documentation api-documentation-tool api-documenter cli rest-api restful-api
Last synced: 1 day ago
JSON representation
a Node.JS CLI tool to easily generate api dog documentation file from your comments
- Host: GitHub
- URL: https://github.com/sina-byn/auto-api-dog
- Owner: sina-byn
- License: mit
- Created: 2024-06-01T22:44:58.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2024-06-07T05:44:02.000Z (5 months ago)
- Last Synced: 2024-10-11T20:11:14.595Z (26 days ago)
- Topics: api, api-doc, api-docs, api-document-generation, api-documentation, api-documentation-tool, api-documenter, cli, rest-api, restful-api
- Language: JavaScript
- Homepage:
- Size: 18.6 KB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# auto-api-dog [](https://www.npmjs.com/package/auto-api-dog) [](https://npmjs.org/package/auto-api-dog) [](https://npmjs.org/package/auto-api-dog)
> Easily document your REST APIs - auto-api-dog is a CLI tool that generates your [api-dog](https://apidog.com/) documentation file from your comments
Please consider following this project's author, [Sina Bayandorian](https://github.com/sina-byn), and consider starring the project to show your :heart: and support.
## Table of Contents
- [Install](#install)
- [Usage](#usage)
- [Format](#format)
- [Fields](#fields)
- [Notes ⚠️](#notes)
- [Options](#options)
## Install
Install with [npm](https://www.npmjs.com/package/auto-api-dog):
```sh
$ npm install -g auto-api-dog
```
## Usage
```json
// package.json
{
"scripts": {
"doc": "auto-api-dog"
}
}
```
Then :
```sh
$ npm run doc
```
Running the command above will output `api.apidog.json` that you can import into the [api-dog](https://apidog.com/) application to have it generate your API documentation.
## Format
Below is the document comment format :
```js
/**
* Description multi-line description
* @name - Create A Post
* @method POST
* @endpoint /
* @maintainer sina-byn
* @status developing
* @query {number} id the id of the post
*
* @payload {object} - {
* "title": {
* "en": "this is the en title",
* "fa": "this is the fa title"
* }
* }
*
* @required {object} - {
* "title": {
* "required": true,
* "value": {
* "en": { "required": true },
* "fa": { "required": true }
* }
* }
* }
*/
```
Visit [comment parser](https://www.npmjs.com/package/comment-parser), and [JSDoc](https://jsdoc.app/) to read more about the documentation comments.
Note that if you use [VS Code](https://code.visualstudio.com/) as your text editor it helps you with the asterisks.
### Fields
Below is the table of all the fields that are defined for the cli. Make sure to read the [notes](#notes) below the table.
| Name | Type | Default | Description |
|------------|--------|---------------------|---------------------------------------------------------------------|
| name | string | "Untitled Endpoint" | the name of the API endpoint - [special syntax](#name-syntax) |
| method | string | | API endpoint's method - must be all in uppercase letters - required |
| status | string | "released" | API dog status - visit [api dog](https://apidog.com/) for more |
| maintainer | string | | the maintainer id from the [api dog](https://apidog.com/) project |
| query | [Param](#param-type) | | defines a single query parameter |
| header | [Param](#param-type) | | defines a single request header |
| cookie | [Param](#param-type) | | defines a single request cookie |
| payload | JSON object | | defines the example payload for the request - [important](#req-body) |
| required | JSON object | | defines the required fields of the payload - [important](#req-body) |
### Notes
-
due to the JSDoc convention the name should follow `@name - {endpoint_name}` the `-` is required or the first word of the name will be ignored
-
`payload` and `required`
- defining the `required` without the `payload` will result in an error
- `payload` is optional and is used to create a JSON schema and a sample request body
- the `required` field optional and is used to define the required fields of the JSON schema
- Note that generating the request body and JSON schema is a complex task, and the developer is responsible for ensuring accuracy and that the types match. For example, in some cases where `payload` and `required` do not match, you might end up with an error; in other cases, your schema might simply not include all the required fields.
-
the `Param` type is a special type
```js
{
type: "string",
name: "post_slug",
description: "desc",
required: true,
example: "first_post",
}
```
Note that support for complex data types for the `Param` type is yet to be added.
**Example**
```js
/**
* @header {number} id the id of the post
*/
```
is equal to
```
{
type: "number",
name: "id",
description: "desc",
required: true,
}
```
`[id]` : `{ required: false }`
`[id=12]` : `{ required: false, example: 12 }`
`[!id=12]` : `{ required: true, example: 12 }`
Note that `!` only works when an example is provided otherwise it will be included in the name of the param.
## Options
| Name | Type | Default | Description |
|-------------|--------|-----------|---------------------------------------------------------------|
| -i, --input | string | "\*\*/\*.js" | glob pattern to match input files that have document comments |
| -n, --name | string | "api" | output json file name - {name}.apidog.json |