From dd87e62536d66f4edd492af5d551d3d361eb2a29 Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Wed, 11 Jan 2023 20:15:17 +0200 Subject: [PATCH] docs: added middleware documentation (#3000) * docs: added a middleware documentation * docs: fixes based on eslint --- .../backend/batch-jobs/customize-import.md | 19 ++--- .../backend/endpoints/add-middleware.md | 72 +++++++++++++++++++ .../content/advanced/backend/endpoints/add.md | 1 + .../price-selection-strategy/override.md | 41 ++++++----- www/docs/sidebars.js | 5 ++ 5 files changed, 112 insertions(+), 26 deletions(-) create mode 100644 docs/content/advanced/backend/endpoints/add-middleware.md diff --git a/docs/content/advanced/backend/batch-jobs/customize-import.md b/docs/content/advanced/backend/batch-jobs/customize-import.md index e1a656fa4b..c8ed6a2793 100644 --- a/docs/content/advanced/backend/batch-jobs/customize-import.md +++ b/docs/content/advanced/backend/batch-jobs/customize-import.md @@ -44,9 +44,12 @@ The batch job strategy class must extend the `AbstractBatchJobStrategy` class wh For example, you can define the following class in the file you created: -```typescript title=src/strategies/import.ts -import { AbstractBatchJobStrategy, BatchJobService } from '@medusajs/medusa' -import { EntityManager } from 'typeorm' +```ts title=src/strategies/import.ts +import { + AbstractBatchJobStrategy, + BatchJobService, +} from "@medusajs/medusa" +import { EntityManager } from "typeorm" class MyImportStrategy extends AbstractBatchJobStrategy { protected batchJobService_: BatchJobService @@ -54,10 +57,10 @@ class MyImportStrategy extends AbstractBatchJobStrategy { protected transactionManager_: EntityManager processJob(batchJobId: string): Promise { - throw new Error('Method not implemented.') + throw new Error("Method not implemented.") } buildTemplate(): Promise { - throw new Error('Method not implemented.') + throw new Error("Method not implemented.") } } @@ -78,10 +81,10 @@ Since only one batch job strategy can handle a batch job type, you can overwrite So, for example, to overwrite the product import strategy set the `batchType` property in your strategy to `product-import`: -```typescript +```ts class MyImportStrategy extends AbstractBatchJobStrategy { - static batchType = 'product-import' - //... + static batchType = "product-import" + // ... } ``` diff --git a/docs/content/advanced/backend/endpoints/add-middleware.md b/docs/content/advanced/backend/endpoints/add-middleware.md new file mode 100644 index 0000000000..0049545e67 --- /dev/null +++ b/docs/content/advanced/backend/endpoints/add-middleware.md @@ -0,0 +1,72 @@ +# How to Add a Middleware + +In this document, you’ll learn how to add a middleware to an existing or custom route in Medusa. + +## Overview + +As the Medusa server is built on top of [Express](https://expressjs.com/), Express’s features can be utilized during your development with Medusa. + +One feature in particular is adding a [middleware](http://expressjs.com/en/guide/using-middleware.html#using-middleware). A middleware is a function that has access to the request and response objects. + +A middleware can be used to perform an action when an endpoint is called or modify the response, among other usages. + +You can add a middleware to an existing route in the Medusa server, a route in a plugin, or your custom routes. + +--- + +## Add a Middleware + +Adding a middleware is very similar to adding a custom endpoint. The middleware must be created either in the `src/api/index.ts` entry point, or other TypeScript or JavaScript files imported into `src/api/index.ts`. + +:::info + +Learn more about creating custom endpoints in [this documentation](./add.md). + +::: + +The following code snippet is an example of adding a middleware: + +```ts title=src/api/index.ts +import { Router } from "express" + +export default () => { + const router = Router() + + router.use("/store/products", (req, res, next) => { + // / perform an action when retrieving products + next() + }) + + return router +} +``` + +This code snippet adds a middleware to the [List Products](/api/store/#tag/Product/operation/GetProducts) endpoint. In the middleware function, you can perform any action. + +Then, you must call the `next` method received as a third parameter in the middleware function to ensure that the endpoint executes after the middleware. + +:::info + +You can learn more about Middlewares and their capabilities in [Express’s documentation](http://expressjs.com/en/guide/using-middleware.html#using-middleware). + +::: + +--- + +## Building Files + +Similar to custom endpoints, you must transpile the files under `src` into the `dist` directory for the server to load them. + +To do that, run the following command before running the Medusa server: + +```bash npm2yarn +npm run build +``` + +--- + +## See Also + +- [Create an Endpoint](./add.md) +- [Store API reference](/api/store) +- [Admin API reference](/api/admin) diff --git a/docs/content/advanced/backend/endpoints/add.md b/docs/content/advanced/backend/endpoints/add.md index e0cc102b78..34c5b1a195 100644 --- a/docs/content/advanced/backend/endpoints/add.md +++ b/docs/content/advanced/backend/endpoints/add.md @@ -295,6 +295,7 @@ npm run build ## See Also +- [Add a Middleware](./add-middleware.md) - [Storefront API Reference](/api/store) - [Admin API Reference](/api/admin) - [Create a Service](./../services/create-service.md). diff --git a/docs/content/advanced/backend/price-selection-strategy/override.md b/docs/content/advanced/backend/price-selection-strategy/override.md index ad21f5949d..dc4b93bf90 100644 --- a/docs/content/advanced/backend/price-selection-strategy/override.md +++ b/docs/content/advanced/backend/price-selection-strategy/override.md @@ -12,46 +12,51 @@ If you’re interested in learning what a price selection strategy is and how it Create a TypeScript or JavaScript file in `src/strategies` of your Medusa server project with a class that extends the `AbstractPriceSelectionStrategy` class: -```typescript title=src/strategies/price.ts -import { AbstractPriceSelectionStrategy, IPriceSelectionStrategy, PriceSelectionContext, PriceSelectionResult } from "@medusajs/medusa"; +```ts title=src/strategies/price.ts +import { + AbstractPriceSelectionStrategy, + IPriceSelectionStrategy, + PriceSelectionContext, + PriceSelectionResult, +} from "@medusajs/medusa" -import { EntityManager } from "typeorm"; +import { EntityManager } from "typeorm" -export default class MyPriceListStrategy extends AbstractPriceSelectionStrategy { +export default class MyStrategy extends AbstractPriceSelectionStrategy { withTransaction(manager: EntityManager): IPriceSelectionStrategy { if (!manager) { return this } - return new MyPriceListStrategy() + return new MyStrategy() } async calculateVariantPrice( variant_id: string, context: PriceSelectionContext ): Promise { - //TODO + // TODO } } ``` -You can use services or repositories in the strategy by adding them to the constructor and updating the parameters passed to the `MyPriceListStrategy` constructor in `withTransaction`. For example: +You can use services or repositories in the strategy by adding them to the constructor and updating the parameters passed to the `MyStrategy` constructor in `withTransaction`. For example: -```typescript +```ts import { AbstractPriceSelectionStrategy, CustomerService, IPriceSelectionStrategy, PriceSelectionContext, - PriceSelectionResult -} from "@medusajs/medusa"; + PriceSelectionResult, +} from "@medusajs/medusa" -export default class MyPriceListStrategy extends AbstractPriceSelectionStrategy { +export default class MyStrategy extends AbstractPriceSelectionStrategy { private customerService: CustomerService constructor({ - customerService + customerService, }) { super() this.customerService = customerService @@ -62,11 +67,11 @@ export default class MyPriceListStrategy extends AbstractPriceSelectionStrategy return this } - return new MyPriceListStrategy({ - customerService: this.customerService + return new MyStrategy({ + customerService: this.customerService, }) } - //... + // ... } ``` @@ -80,10 +85,10 @@ This method accepts the variant ID as a first parameter and the [context](./inde This method must return an object having the following fields: -```typescript noReport +```ts noReport { - originalPrice, //number | null - calculatedPrice, //number | null + originalPrice, // number | null + calculatedPrice, // number | null prices // MoneyAmount[] } ``` diff --git a/www/docs/sidebars.js b/www/docs/sidebars.js index a86049be54..259e647159 100644 --- a/www/docs/sidebars.js +++ b/www/docs/sidebars.js @@ -368,6 +368,11 @@ module.exports = { id: "advanced/backend/endpoints/add", label: "Create an Endpoint" }, + { + type: "doc", + id: "advanced/backend/endpoints/add-middleware", + label: "Add a Middleware" + }, { type: "doc", id: "advanced/backend/services/create-service",