Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/n3ps/json-schema-to-jsdoc
Generate JSDoc from JSON Schema
https://github.com/n3ps/json-schema-to-jsdoc
jsdoc json-schema
Last synced: 3 days ago
JSON representation
Generate JSDoc from JSON Schema
- Host: GitHub
- URL: https://github.com/n3ps/json-schema-to-jsdoc
- Owner: n3ps
- License: isc
- Created: 2017-04-05T23:24:51.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2024-06-21T14:06:21.000Z (5 months ago)
- Last Synced: 2024-10-02T20:46:44.911Z (about 1 month ago)
- Topics: jsdoc, json-schema
- Language: JavaScript
- Homepage: https://francisn.com/json-schema-to-jsdoc/
- Size: 818 KB
- Stars: 30
- Watchers: 2
- Forks: 11
- Open Issues: 6
-
Metadata Files:
- Readme: readme.md
- License: LICENSE-ISC.txt
Awesome Lists containing this project
README
[](https://www.npmjs.com/package/json-schema-to-jsdoc)
[](github.com/n3ps/json-schema-to-jsdoc/actions/workflows/node.js.yml/badge.svg)
[](https://snyk.io/test/github/n3ps/json-schema-to-jsdoc)
[](https://lgtm.com/projects/g/n3ps/json-schema-to-jsdoc/alerts)
[](https://lgtm.com/projects/g/n3ps/json-schema-to-jsdoc/context:javascript)
# JSON Schema to JSDoc
Useful when you already have a JSON Schema and want to document the types you want to validate. Works with subschema definitions.
## Usage
```js
const jsdoc = require('json-schema-to-jsdoc')
const schema = {
"title": "Person",
"type": "object",
"properties": {
"name": {"type": "string", "description": "A person's name"},
"age": {"type": "integer", "description": "A person's age"}
},
"required": ["name"]
}
jsdoc(schema /* , optionsObject */)
```
### Output
```js
/**
* @typedef {object} Person
* @property {string} name A person's name
* @property {integer} [age] A person's age
*/
```
## Examples
#### `hyphenatedDescriptions`
```js
jsdoc(schema, {
hyphenatedDescriptions: true
})
```
```js
/**
* @typedef {object} Person
* @property {string} name - A person's name
* @property {integer} [age] - A person's age
*/
```
#### `autoDescribe`
```js
jsdoc(schema, {
autoDescribe: true
})
```
```js
/**
* Represents a Person object
* @typedef {object} Person
* @property {string} name A person's name
* @property {integer} [age] A person's age
*/
```
#### `types`
```js
jsdoc(schema, {
types: {
object: 'PlainObject'
}
})
```
```js
/**
* @typedef {PlainObject} Person
* @property {string} name A person's name
* @property {integer} [age] A person's age
*/
```
#### `formats`
```js
const schema = {
title: 'Info',
type: 'object',
properties: {
code: {
type: 'string', format: 'html', description: 'The HTML source'
}
},
required: ['code']
}
jsdoc(schema, {
formats: {
html: {
string: 'HTML'
}
}
})
```
```js
/**
* @typedef {object} Info
* @property {HTML} code The HTML source
*/
```
## Options
`addDescriptionLineBreak`: boolean
Inserts an empty line when `autoDescribe` is `false` and the schema
`description` is empty. Defaults to `false`.
`autoDescribe`: boolean
Adds a description (`"Represents a/n [ ]"`) when the
schema has no `description`. Defaults to `false`.
`capitalizeProperty`: boolean
When `propertyNameAsType` is `true`, capitalizes the property-as-type,
i.e., `MyTitle` in `@property {MyTitle} myTitle`. Defaults to `false.`
`capitalizeTitle`: boolean
If a schema `title` is present, capitalizes the schema's `title` in the
output of `@typedef {myType} title`. Defaults to `false`.
`defaultPropertyType`: null | string
Used when no schema type is present. Defaults to `"*"`.
- `string`: If set to a string, that string will be used (e.g.,
"any", "JSON", "external:JSON"). Note that jsdoc recommends `*` for
any, while TypeScript uses "any". If one defines one's own "JSON"
type, one could use that to clarify that only JSON types are used.
- `null`: Will avoid any type brackets or type being added.
`descriptionPlaceholder`: boolean
If `false` and there is no `description` for the object `@property`,
this will avoid a hyphen or even a space for `{description}` within
`@property {name}{description}`. Defaults to `false`.
`hyphenatedDescriptions`: boolean
Inserts a hyphen + space in the `{description}` portion of
`@property {name}{description}` (will add a space, however, unless
`descriptionPlaceholder` is `false`). Defaults to `false`.
`ignore`: string[]
Property names to ignore adding to output. Defaults to empty array.
`indent`: number
How many of `indentChar` to precede each line. Defaults to `0` (no
indent). Note that a single space will be added in addition to the
indent for every line of the document block after the first.
`indentChar`: string
Character to use when `indent` is set (e.g., a tab or space).
Defaults to a space.
`maxLength`: number | boolean
- `number`: Enforce a maximum length in `@typedef` and `@property`
descriptions (taking into account `indent`/`indentChar`).
- `false`: Prevent wrapping entirely. Defaults to `false`.
`objectTagName`: string
Tag name to use for objects. Defaults to `typedef`.
`propertyNameAsType`: boolean
Indicates that the property name (for objects) should be used as the
type name (optionally capitalized with `capitalizeProperty`). Defaults
to `false`.
`types`: null | {[schemaType: string]: string}
Used to determine output of curly-bracketed type content within
`@typedef {...}`.
If `null` no curly brackets or type content will be shown with the
`@typedef` at all. If the schema `type` matches a property in the object map, and it maps to the empty string, an empty `{}` will result. Otherwise, if there is a `type` match, that string will be used as the curly bracketed type, or if there is no match, the schema's `type` will be used for the bracketed content. Defaults to an empty object map (will always just use the schema's `type`). This property may be used to change the likes of `@typedef {object}` to `@typedef {PlainObject}`.