## 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
Add missing x-codegen + fix schema naming and $ref
## Why
OAS code generator was missing information to be able to match current JS client.
## How
Ensure OAS matches JS client methods.
## What
Include `/admin` and `/store` in OAS paths URLs
## Why
Allow for generating a combined OAS that include routes for both "admin" and "store" endpoint.
Fix potential issues with code generator where routes are not prefixed with "admin" and "store" leading to 404 errors.
## 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 paths to be prefixed with /admin.
* Run `yarn redocly preview-docs docs/api/store/openapi.yaml --config=./docs-util/redocly/config.yaml`
* Expect paths to be prefixed with /store.
## What
Include packages/ subdirectories in medusa-dev packages discovery.
## Why
We started to use subdirectories in the monorepo `packages/` directory in order to better organize packages.
Packages in subdirectories were invisible to `medusa-dev` and could not be copied.
## How
Rely on monorepo package.json workspace glob patterns to discover packages that can be published to the local npm registry.
## What
Allow `medusa-oas` CLI to generate API client code from an OAS json file.
## Why
Manually maintaining API clients is time consuming and error prone. We wish to automate the process by using code generation strategies.
We also wish to eliminate direct import from `@medusajs/medusa` in clients which can lead to unwanted side effects like importing unnecessary dependencies.
## How
Fork and customize an OAS code generator library that is TypeScript friendly.
Attempt to match the interface and signature of our current client packages: `@medusajs/medusa-js`, `medusa-react`
Add a new `client` command to the `medusa-oas` CLI as the main interface to interact with the code generation tooling.
## Test
### Prerequisites
* From the root of the monorepo:
* `yarn install`
* `yarn build`
### Case - all in one build
* From the root of the monorepo:
* Run `yarn medusa-oas oas --out-dir ~/tmp/oas --type store`
* Run `yarn medusa-oas client --src-file ~/tmp/oas/store.oas.json --out-dir ~/tmp/client-store --type store`
* Expect `~/tmp/client-store` to contain the following files and directories:
```
core/
hooks/
models/
services/
index.ts
MedusaStore.ts
useMedusaStore.tsx
```
### Case - types only
* From the root of the monorepo:
* Run `yarn medusa-oas oas --out-dir ~/tmp/oas --type store`
* Run `yarn medusa-oas client --src-file ~/tmp/oas/store.oas.json --out-dir ~/tmp/client-types --type store --component types`
* Expect `~/tmp/client-types` to contain the following files and directories:
```
models/
index.ts
```
### Case - client only
* From the root of the monorepo:
* Run `yarn medusa-oas oas --out-dir ~/tmp/oas --type store`
* Run `yarn medusa-oas client --src-file ~/tmp/oas/store.oas.json --out-dir ~/tmp/client-only --type store --component client --types-package @medusajs/client-types`
* Expect `~/tmp/client-only` to contain the following files and directories:
```
core/
services/
index.ts
MedusaStore.ts
```
## Scope
Store routes
## What
Add OAS `required` to response schemas.
## Why
Code generator can use the `required` property of a schema to mark fields as optional or not when generating TS types.
## Test
* Run `yarn build`
* Run `yarn openapi:generate`
* Run `yarn redocly preview-docs docs/api/store/openapi.yaml --config=docs-util/redocly/config.yaml`
* Open the documentation preview URL in a browser (http://127.0.0.1:8080)
* Expect responses to have their fields declared as `required`
## Scope
Admin routes
## What
Add OAS `required` to response schemas.
## Why
Code generator can use the `required` property of a schema to mark fields as optional or not when generating TS types.
## Test
* Run `yarn build`
* Run `yarn openapi:generate`
* Run `yarn redocly preview-docs docs/api/admin/openapi.yaml --config=docs-util/redocly/config.yaml`
* Open the documentation preview URL in a browser (http://127.0.0.1:8080)
* Expect responses to have their fields declared as `required`
## 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`.
* feat(medusa): Cleanup swap creation flow
* revert test and package
* fix unit tests
* fix swap seeder that does not include the tax lines on the return line item
---------
Co-authored-by: Oliver Windall Juhl <59018053+olivermrbl@users.noreply.github.com>
What:
Assign the default sales channel if none is provided while creating a new product.
FIXES: CORE-1114
Co-authored-by: Oliver Windall Juhl <59018053+olivermrbl@users.noreply.github.com>
### Scope
Models R to U
### What
Refactor OAS for models to accurately represent their shape in API responses.
### Why
About 33% of model fields are not accurately represented in the OAS. Most of the issues are:
- fields that can not be omitted in the response are not declared as `required`
- fields that could return `null` as their value are not declared as `nullable: true`
When using a code generator, these OAS issues would lead to inaccurate response shapes in the generated client.
### How
#### nullable
Fields meeting at least one of the following condition will be represented as `nullable: true` in OAS:
* The field is decorated with `@Column({ nullable: true })`
* The field is decorated with `@OneToOne`, `@ManyToOne`
* The field is decorated with `@DeleteDateColumn`
#### optional
Fields meeting at least one of the following conditions will never be listed as `required` in OAS and will be considered optional and could be omitted in the response:
* The field is decorated with `@OneToOne`, `@ManyToOne`, `@OneToMany`, `@ManyToMany`
* The field is decorated with `@FeatureFlagColumn`
* The field is decorated with `@Column({select: false})`
* The field is representing dynamic values not persisted in the database
Fields not meeting any of the conditions above will be declared as `required` and are expected to be present in the response.
### Test
* Ran OAS validator.
* Ran docs build script.
Expect OAS changes to be reflected in the API documentation.
### Scope
Models PA to PU
### What
Refactor OAS for models to accurately represent their shape in API responses.
### Why
About 33% of model fields are not accurately represented in the OAS. Most of the issues are:
- fields that can not be omitted in the response are not declared as `required`
- fields that could return `null` as their value are not declared as `nullable: true`
When using a code generator, these OAS issues would lead to inaccurate response shapes in the generated client.
### How
#### nullable
Fields meeting at least one of the following condition will be represented as `nullable: true` in OAS:
* The field is decorated with `@Column({ nullable: true })`
* The field is decorated with `@OneToOne`, `@ManyToOne`
* The field is decorated with `@DeleteDateColumn`
#### optional
Fields meeting at least one of the following conditions will never be listed as `required` in OAS and will be considered optional and could be omitted in the response:
* The field is decorated with `@OneToOne`, `@ManyToOne`, `@OneToMany`, `@ManyToMany`
* The field is decorated with `@FeatureFlagColumn`
* The field is decorated with `@Column({select: false})`
* The field is representing dynamic values not persisted in the database
Fields not meeting any of the conditions above will be declared as `required` and are expected to be present in the response.
### Test
* Ran OAS validator.
* Ran docs build script.
Expect OAS changes to be reflected in the API documentation.
### Scope
Models F to O
### What
Refactor OAS for models to accurately represent their shape in API responses.
### Why
About 33% of model fields are not accurately represented in the OAS. Most of the issues are:
- fields that can not be omitted in the response are not declared as `required`
- fields that could return `null` as their value are not declared as `nullable: true`
When using a code generator, these OAS issues would lead to inaccurate response shapes in the generated client.
### How
#### nullable
Fields meeting at least one of the following condition will be represented as `nullable: true` in OAS:
* The field is decorated with `@Column({ nullable: true })`
* The field is decorated with `@OneToOne`, `@ManyToOne`
* The field is decorated with `@DeleteDateColumn`
#### optional
Fields meeting at least one of the following conditions will never be listed as `required` in OAS and will be considered optional and could be omitted in the response:
* The field is decorated with `@OneToOne`, `@ManyToOne`, `@OneToMany`, `@ManyToMany`
* The field is decorated with `@FeatureFlagColumn`
* The field is decorated with `@Column({select: false})`
* The field is representing dynamic values not persisted in the database
Fields not meeting any of the conditions above will be declared as `required` and are expected to be present in the response.
### Test
* Ran OAS validator.
* Ran docs build script.
Expect OAS changes to be reflected in the API documentation.
### Scope
Models A to D
### What
Refactor OAS for models to accurately represent their shape in API responses.
### Why
About 33% of model fields are not accurately represented in the OAS. Most of the issues are:
- fields that can not be omitted in the response are not declared as `required`
- fields that could return `null` as their value are not declared as `nullable: true`
When using a code generator, these OAS issues would lead to inaccurate response shapes in the generated client.
### How
#### nullable
Fields meeting at least one of the following condition will be represented as `nullable: true` in OAS:
* The field is decorated with `@Column({ nullable: true })`
* The field is decorated with `@OneToOne`, `@ManyToOne`
* The field is decorated with `@DeleteDateColumn`
#### optional
Fields meeting at least one of the following conditions will never be listed as `required` in OAS and will be considered optional and could be omitted in the response:
* The field is decorated with `@OneToOne`, `@ManyToOne`, `@OneToMany`, `@ManyToMany`
* The field is decorated with `@FeatureFlagColumn`
* The field is decorated with `@Column({select: false})`
* The field is representing dynamic values not persisted in the database
Fields not meeting any of the conditions above will be declared as `required` and are expected to be present in the response.
### Test
* Ran OAS validator.
* Ran docs build script.
Expect OAS changes to be reflected in the API documentation.
