Files

Shahed Nasser bb87db8342 docs: prep for v2 documentation (#6710 )

This PR includes documentation that preps for v2 docs (but doesn't introduce new docs).

_Note: The number of file changes in the PR is due to find-and-replace within the `references` which is unavoidable. Let me know if I should move it to another PR._

## Changes

- Change Medusa version in base OAS used for v2.
- Fix to docblock generator related to not catching all path parameters.
- Added typedoc plugin that generates ER Diagrams, which will be used specifically for data model references in commerce modules.
- Changed OAS tool to output references in `www/apps/api-reference/specs-v2` directory when the `--v2` option is used.
- Added a version switcher to the API reference to switch between V1 and V2. This switcher is enabled by an environment variable, so it won't be visible/usable at the moment.
- Upgraded docusaurus to v3.0.1
- Added new Vale rules to ensure correct spelling of Medusa Admin and module names.
- Added new components to the `docs-ui` package that will be used in future documentation changes.

2024-03-18 07:47:35 +00:00

src

docs: prep for v2 documentation (#6710 )

2024-03-18 07:47:35 +00:00

.env.sample

docs-util: created docblock-generator tool (#6096 )

2024-01-24 11:13:40 +01:00

package.json

docs-util: support generating OAS in docblock generator (#6338 )

2024-02-13 08:40:04 +00:00

README.md

docs-util: support generating OAS in docblock generator (#6338 )

2024-02-13 08:40:04 +00:00

tsconfig.json

docs-util: created docblock-generator tool (#6096 )

2024-01-24 11:13:40 +01:00

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 docs-util/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.