- Fix GitHub action to run on push and check if the commit message is "chore: Release". Only then are TSDocs generated and a PR is opened.
- Add an option to pass to the `run:release` method of the docblock generator a release tag. This is helpful in cases when the GitHub action fails for any reason.
- Add scripts that checks the message of a commit.
This PR changes the original process of generating docblocks through actions. The process now is:
1. When a PR is merged for the branch `changeset-release/develop`, the docblock generator tool us used to generate docblocks for the changed files. The changed files are determined by retrieving all comments since the last release and the files in each of those commits.
2. If there are changes after using the docblock generator tool, a PR is opened in the branch `chore/generate-tsdocs`.
3. Once the `chore/generate-tsdocs` is merged, it triggers an action that generates the references for the docs. This changes the previous behaviour of generating references on a new release.
Both actions (that runs the docblock generator tool and that generates references for the docs) can also be triggered manually.
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
- Added anchor links to items in parameter components
- Added sectionTitle prop in markdown theme
Note: Due to the second point, the change requires generating references to see the anchor links, which would result in a big diff in this PR. Instead, next time the references are generated for a release, this feature will available for use.
* adjusted configurations
* enhancements to tool and configurations
* change reference in docs
* fixed issue in workflows reference
* added project name
* more optimizations
* fix context error
* added a types reference
* resolved missing types
* fix reference reflection types not having children
* add an expand url parameter
* added new option to the README
* added details about new option
* chore(docs-util): Improve generate references script and action
* added if condition for API reference
* fix api reference condition
* fix description of action
* fix body value
* fix step name
* docs: change format of module reference
* description fix
* update structure + comments
* added new options to README
* small text fix
* change section ordering
* change how required/optional are shown
* remove optional text
* docs: redesigned accordion
* adjusted tsdoc of methods and types in pricing module
* finished adding tsdocs
* small fixes
* remove reference files
* added github action
* fix typo in outPath
* Update packages/types/src/shared-context.ts
Co-authored-by: Carlos R. L. Rodrigues <37986729+carlos-r-l-rodrigues@users.noreply.github.com>
* fix sharedContext description
* changed branch name of action
* added ignore for is_dynamic
* added private remark
---------
Co-authored-by: Carlos R. L. Rodrigues <37986729+carlos-r-l-rodrigues@users.noreply.github.com>
## What
New `medusa-oas docs` to improve OAS compatibility with for Redocly API documentation viewer and handle deep circular references.
## Why
We wish to share the tooling we have been using to generate our public API documentation.
## How
* Move `/docs-utils/redocly` under `medusa-oas-cli` package.
* Move some of the operations from `oas-github-ci/scripts/build-openapi.js` under the `medusa-oas docs` command.
* Improve DevX when dealing with circular references by outputting precise troubleshooting recommendations in the error message.
* Extract some common operations in utility methods.
## Tests
### Step 1
* Run `yarn install`
* Run `yarn build`
* Run `yarn openapi:generate --dry-run`
* Expect same behaviour as before where OAS is validated and circular references are checked.
### Step 2
* Run `yarn openapi:generate`
* Expect same behaviour as before where API documentation is generated in `/docs`
### Step 3
* Move to the `packages/oas/medusa-oas-cli`
* Run `yarn medusa-oas oas --type store --out-dir ~/tmp/oas` to generate the raw OAS file.
* Run `yarn medusa-oas docs --src-file ~/tmp/oas/store.oas.json --preview`
* Open url from the console output in a browser
* Expect a preview of the API documentation using Redocly.
### Step 4
* Run `yarn medusa-oas docs --src-file ~/tmp/oas/store.oas.json --out-dir ~/tmp/docs/store --clean --split`
* Expect a similiar output as `yarn openapi:generate`
### Step 5
* Run `yarn medusa-oas docs --src-file ~/tmp/oas/store.oas.json --out-dir ~/tmp/docs/store --clean --html`
* Expect `index.html` to have been created.
* Run `npx http-server ~/tmp/docs/store -p 8000`
* Open http://127.0.0.1:8000 in a browser.
* Expect a zero-dependency static rendering of the API documentation using Redocly.
### Step 6
* To emulate an unhandled circular reference, edit [packages/oas/medusa-oas-cli/redocly/redocly-config.yaml](d180f47e16/packages/oas/medusa-oas-cli/redocly/redocly-config.yaml (L9-L10)) and comment out "Address: - Customer"
* Run `yarn medusa-oas docs --src-file ~/tmp/oas/store.oas.json --dry-run`
* Expect an error message with a hint on how to resolve the issue.
* Create a file `~/tmp/redocly-config.yaml` and paste in the recommendation from the error message.
* Run `yarn medusa-oas docs --src-file ~/tmp/oas/store.oas.json --dry-run --config ~/tmp/redocly-config.yaml`
* Expect Dry run to succeed.
## What
Pluralize OAS tags
## Why
OAS tags are commonly used by code generator to group routes under a name space based on a tag.
Our JS client convention is to use plural, e.g: client.products, client.customers. In order to minimize friction when migrating to a client generated from OAS, tags should be plural as well.
## How
Match tag naming with JS client resource naming.
## Test
* Run `yarn build`
* Run `yarn openapi:generate`
* Run `yarn redocly preview-docs docs/api/admin/openapi.yaml --config=./docs-util/redocly/config.yaml`
* Expect side menu items to be plural.
* Run `yarn redocly preview-docs docs/api/store/openapi.yaml --config=./docs-util/redocly/config.yaml`
* Expect side menu items to be plural.
## What
Introduce a CLI for extracting OAS from the core `medusa` package.
## Why
We need to decouple OAS tooling from documentation tooling in order to allow packages and external systems to leverage our OAS has a dependency.
## How
Introduce a new OAS workspace within packages in order to organize current and future OAS related package. Only 1 OAS package for now.
Introduce a new CLI only package to act as the main gateway for all upcoming OAS tooling. Only 1 command for now.
Update documentation tooling pertaining to OAS to use the CLI instead.
## Test
### Prerequisite
From the monorepo root:
* `yarn install`
* `yarn build`
### Documentation
#### Case - validation only - success
* Run `yarn openapi:generate --dry-run`
* Expect console output `🟢 Valid OAS` but no mention of `🔵 Exported OAS`
#### Case - validation only - invalid
* Introduce a bug by renaming `@schema Cart` to `@schema Kart` in [models/cart.ts](0adb0d9ff9/packages/medusa/src/models/cart.ts (L2))
* Run `yarn build` to update `@medusajs/medusa` package with the bug.
* Run `yarn openapi:generate --dry-run`
* Expect console output `🔴 Invalid OAS` with a stack trace of the issue.
#### Case - docs generation
* Run `yarn openapi:generate`
* Expect `docs/api/` directory to contain:
* `admin.oas.json` (raw OAS)
* `store.oas.json` (raw OAS)
* `admin.oas.yaml` (sanitized OAS)
* `store.oas.yaml` (sanitized OAS)
* `admin/` (updated redocly split output)
* `store/` (updated redocly split output)
### CLI
#### Case - crawl additional paths
* From a local medusa server (`medusa-starter-default`), add an `index.ts` file in `src/models/`
* In the `index.ts`, add dummy OAS JSDoc like `/** @schema Foobar */`
* From the root of the monorepo, run `yarn medusa-oas --type store --paths path-to-medusa-server/src`
* Expect a `store.oas.json` to be created at the root of the monorepo.
* The `store.oas.json` should contain an additional `Foobar` entry in `components.schemas`.
### What
Add OAS build step to patch known circular references that prevent Redocly from rendering the API documentation.
### Why
We've encountered crashing and loading issues with Redocly when the OAS contained circular references. We have been working around the limitation by omitting some known problematic $ref in our source OAS. We wish to move away from this strategy in order to always explicitly include $ref in our OAS.
### How
We are introducing a custom Redocly CLI plugin that will replace `$ref` by `type: object` base on a configurable set of instructions. These instructions can be modified in `docs-util/redocly/config.yaml`
We are adding a `redocly bundle` step in the current OAS build process in order to sanitize problematic circular references.
We updated the redocly-cli package version in order to ensure that plugins are supported.
### Test
We will use [Cart.payment](fd5c185159/packages/medusa/src/models/cart.ts (L72-L74)) to ensure that the new process is properly sanitizing.
* Run `yarn openapi:generate`
* Open `docs/api/store/components/schemas/Cart.yaml`
* Expect the `payment` property to have been sanitized to `type: object`
* Run `yarn redocly preview-docs docs/api/store/openapi.yaml --config=docs-util/redocly/config.yaml`
* Visit http://127.0.0.1:8080/#tag/Cart/operation/GetCartsCart
* In the response, expect cart.payment to not list the properties of the Payment schema.
