Files

Shahed Nasser f9d86683e5 docs-util: update knowledge base of docblock-generator (#8323 )

* docs: update knowledge base for functions and filters

* fix build error

2024-07-29 12:34:25 +03:00

src

docs-util: update knowledge base of docblock-generator (#8323 )

2024-07-29 12:34:25 +03:00

.env.sample

…

package.json

docs-util: add docblock generator for models built with DML (#8296 )

2024-07-29 10:11:39 +02:00

README.md

…

tsconfig.json

…

README.md

docblock-generator

A CLI tool that can be used to generate TSDoc docblocks and OAS for TypeScript/JavaScript files under the packages directory of the main monorepo.

Prerequisites

Run the yarn command to install dependencies.
Copy the .env.sample to .env and change the MONOREPO_ROOT_PATH variable to the absolute path to the monorepo root.
Run the yarn build command to build source files.

Usage

Generate for a specific file

Run the following command to run the tool for a specific file:

yarn start run /absolute/path/to/file.ts

Generate for git-changed files

Run the following command to run the tool for applicable git file changes:

yarn start run:changes

Generate for a specific commit

Run the following command to run the tool for a commit SHA hash:

yarn start run:commit <commit-sha>

Where <commit-sha> is the SHA of the commit. For example, e28fa7fbdf45c5b1fa19848db731132a0bf1757d.

Generate for a release

Run the following command to run the tool on commits since the latest release.

yarn start run:release

Clean OAS

Run the following command to clean up the OAS output files and remove any routes that no longer exist:

yarn start clean:oas

This command will also remove tags and schemas not used.

How it Works

Generating OAS

If a node is an API route, it generates OAS comments rather than TSDoc comments. The OAS comments are generated and placed in new/existing files under the www/utils/generated/oas-output/operations directory.

Generating TSDoc Docblocks

If a note isn't an API Route and it complies with the specified conditions, TSDoc docblocks are generated for it.

Files under the packages/medusa/src/api or api-v2 directories are considered incompatible, so any files under these directories won't have TSDoc docblocks generated for them.

Common Options

This section includes options that you can pass to any of the mentioned commands.

--generate-examples

If this option is passed, the tool will try to generate OAS examples. Currently, it will only try to generate JS Client examples.

cURL examples are always generated regardless of this option.

--type

You can use this option to specify the type of docs to generate. Possible values are:

all: (default) Generate all doc types.
docs: Generate only TSDoc docblocks.
oas: Generate only OAS docblocks/files.