Write indentable OpenApi/Swagger jsDoc comments.
This VSCode extension targets this issue on StackOverflow. Basically, when writing your API spec in YAML with swagger-jsdoc, it is impossible to get automatic indentation and formatting inside the comment blocks. Thus, you end up either writing it in JSON or manually adding spaces/tabs for each line, which is really tedious.
The extension allows you to write your spec inside comment blocks and then format it so swagger-jsdoc can parse it and generate your spec.
VSCode enables automatic indentation when there's no preceding asterisk (
*
).
/**
* You won't be able to get automatic indentation here
* or here
*
but you'll
get it here,
when there's no asterisk
preceding the line
*/
Install the extension from the installation page.
For the extension to correctly parse your comment block, it should follow the following guidelines:
- The spec has to start with either
@swagger
or@openapi
- The comment should start with
/**
- No line (of the spec only) should start with an asterisk (
*
) - It can contain regular comments preceded by an asterisk before the spec
- Before running the extension you must place your cursor within the comment block
Write your spec
/**
* Spec for the route /auth/register.
*
@openapi
/auth/register:
post:
summary: Register as user
tags:
- Auth
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- name
- email
- password
properties:
name:
type: string
email:
type: string
format: email
description: Must be unique
password:
type: string
format: password
minLength: 8
description: At least one number and one letter
*/
router.post("/auth/register", authMiddleware.validate, authController.register);
Place your cursor within the comment block, press cmd + shift + P
(MacOS) or ctrl + shift + P
(Windows) and search for Swagger jsDoc: Format spec
.
The extension will:
- Run prettier to fix/catch indentation errors
- Add an asterisk at the start of each line
- Replace your comment block with the formatted one
- Respect any indentation of your block
/**
* Spec for the route /auth/register.
*
* @openapi
* /auth/register:
* post:
* summary: Register as user
* tags:
* - Auth
* requestBody:
* required: true
* content:
* application/json:
* schema:
* type: object
* required:
* - name
* - email
* - password
* properties:
* name:
* type: string
* email:
* type: string
* format: email
* description: Must be unique
* password:
* type: string
* format: password
* minLength: 8
* description: At least one number and one letter
*
*
* More regular comments here
*/
router.post("/auth/register", authMiddleware.validate, authController.register);
Optionally run swagger-jsdoc to generate your spec.
$ yarn swagger-jsdoc -d docs/api/definition.yml src/api/routes/v1/**.ts -o docs/api/specification.yml
It is possible to undo the formatting for easy editing (thanks @doctorfred). Works the same as formatting, but instead removes the asterisks so you can edit the spec while being able to indent it.
Place your cursor within the comment block, press cmd + shift + P
(MacOS) or ctrl + shift + P
(Windows) and search for Swagger jsDoc: Unformat spec
.
Then you can just format it again.
MIT