diff --git a/README.md b/README.md index e21df2039..74c267689 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,7 @@ - [Directory Tree](#directory-tree) - [React Preferences](#react-preferences) - [Code Linting and Format](#code-linting-and-format) + - [API Slug Mapping](#api-slug-mapping) - [Commits](#commits) - [How to make a commit](#how-to-make-a-commit) - [Branches](#branches) @@ -213,6 +214,31 @@ flowchart TB You might want to configure ESLint and Prettier in your code editor to see errors and correction suggestions at development time. +### API Slug Mapping + +The mapping between API display names and their corresponding slugs is centralized in a single file to make maintenance easier: + +``` +src/utils/api-slug-mapping.ts +``` + +This mapping is used in various parts of the application: + +1. In `getReferencePaths.ts` to generate paths for API reference documentation +2. In `api/openapi/[slug].tsx` to handle OpenAPI schema requests +3. In `api/postman/[slug].tsx` to handle Postman collection requests + +When adding a new API or modifying an existing one, you should update only this file, and all parts of the system that use this mapping will automatically get the updated information. + +Example: +```typescript +// src/utils/api-slug-mapping.ts +export const apiSlugMap: { [key: string]: string } = { + 'VTEX - New API': 'new-api-slug', + // ... other mappings +} +``` + ### Commits By simplicity, we have three types of commits: diff --git a/src/pages/api/openapi/[slug].tsx b/src/pages/api/openapi/[slug].tsx index 1614ade0c..b7dc3dcbf 100644 --- a/src/pages/api/openapi/[slug].tsx +++ b/src/pages/api/openapi/[slug].tsx @@ -4,63 +4,9 @@ export const config = { }, } -const referencePaths = objectFlip({ - 'VTEX - Antifraud Provider API': 'antifraud-provider-protocol', - 'VTEX - Legacy CMS Portal API': 'legacy-cms-portal-api', - 'VTEX - Catalog API Seller Portal': 'catalog-api-seller-portal', - 'VTEX - Catalog API': 'catalog-api', - 'VTEX - Checkout API': 'checkout-api', - 'VTEX - Checkout Configuration API': 'checkout-configuration-api', - 'VTEX - Customer Credit API': 'customer-credit-api', - 'VTEX - GiftCard Hub API': 'giftcard-hub-api', - 'VTEX - Giftcard API': 'giftcard-api', - 'VTEX - Giftcard Provider Protocol': 'giftcard-provider-protocol', - 'VTEX - Headless CMS API': 'headless-cms-api', - 'VTEX - Intelligent Search API': 'intelligent-search-api', - 'VTEX - License Manager API': 'license-manager-api', - 'VTEX - Logistics API': 'logistics-api', - 'VTEX - Marketplace APIs': 'marketplace-apis', - 'VTEX - Marketplace APIs - Suggestions': 'marketplace-apis-suggestions', - 'VTEX - Marketplace APIs - Sent Offers': 'marketplace-apis-offer-management', - 'VTEX - Marketplace Protocol - External Marketplace Mapper': - 'marketplace-protocol-external-marketplace-mapper', - 'VTEX - Marketplace Protocol - External Marketplace Orders': - 'marketplace-protocol-external-marketplace-orders', - 'VTEX - Marketplace Protocol - External Seller Fulfillment': - 'marketplace-protocol-external-seller-fulfillment', - 'VTEX - Marketplace Protocol - External Seller Marketplace': - 'marketplace-protocol', - 'VTEX - Master Data API - v2': 'master-data-api-v2', - 'VTEX - MasterData API - v10.2': 'masterdata-api', - 'VTEX - Message Center API': 'message-center-api', - 'VTEX - Orders API PII version': 'orders-api-pii-version', - 'VTEX - Orders API': 'orders-api', - 'VTEX - Payment Provider Protocol': 'payment-provider-protocol', - 'VTEX - Payments Gateway API': 'payments-gateway-api', - 'VTEX - Pick and Pack Last Mile Protocol API': 'pick-and-pack-protocol-api', - 'VTEX - Pick and Pack Order Changes API': 'pick-and-pack-order-changes-api', - 'VTEX - Policies System API': 'policies-system-api', - 'VTEX - Pricing API': 'pricing-api', - 'VTEX - Pricing Hub': 'pricing-hub', - 'VTEX - Profile System': 'profile-system', - 'VTEX - Promotions & Taxes API': 'promotions-and-taxes-api', - 'VTEX - Reviews and Ratings API': 'reviews-and-ratings-api', - 'VTEX - SKU Bindings API': 'sku-bindings-api', - 'VTEX - Search API': 'search-api', - 'VTEX - Session Manager API': 'session-manager-api', - 'VTEX - Subscriptions API v3': 'subscriptions-api-v3', - 'VTEX - Tracking': 'tracking', - 'VTEX - VTEX Do API': 'vtex-do-api', - 'VTEX - VTEX ID API': 'vtex-id-api', - 'VTEX - VTEX Shipping Network API': 'vtex-shipping-network-api', - 'VTEX - Promotions & Taxes API - v2': 'promotions-and-taxes-api-v2', - 'VTEX - Intelligent Search Events API - Headless': - 'intelligent-search-events-api-headless', - 'VTEX - Data Subject Rights': 'data-subject-rights-api', - 'VTEX - Buyer Organizations': 'buyer-organizations', - 'VTEX - Audience API': 'audience-api', - 'VTEX - Ad Network API': 'vtex-ad-network-api', -}) +import { apiSlugMap } from 'utils/api-slug-mapping' + +const referencePaths = objectFlip(apiSlugMap) function objectFlip(obj: { [x: string]: string }) { return Object.keys(obj).reduce((ret, key) => { diff --git a/src/pages/api/postman/[slug].tsx b/src/pages/api/postman/[slug].tsx index 9ce437fd8..d280f31b8 100644 --- a/src/pages/api/postman/[slug].tsx +++ b/src/pages/api/postman/[slug].tsx @@ -4,63 +4,9 @@ export const config = { }, } -const referencePaths = objectFlip({ - 'VTEX - Antifraud Provider API': 'antifraud-provider-protocol', - 'VTEX - Legacy CMS Portal API': 'legacy-cms-portal-api', - 'VTEX - Catalog API Seller Portal': 'catalog-api-seller-portal', - 'VTEX - Catalog API': 'catalog-api', - 'VTEX - Checkout API': 'checkout-api', - 'VTEX - Checkout Configuration API': 'checkout-configuration-api', - 'VTEX - Customer Credit API': 'customer-credit-api', - 'VTEX - GiftCard Hub API': 'giftcard-hub-api', - 'VTEX - Giftcard API': 'giftcard-api', - 'VTEX - Giftcard Provider Protocol': 'giftcard-provider-protocol', - 'VTEX - Headless CMS API': 'headless-cms-api', - 'VTEX - Intelligent Search API': 'intelligent-search-api', - 'VTEX - License Manager API': 'license-manager-api', - 'VTEX - Logistics API': 'logistics-api', - 'VTEX - Marketplace APIs': 'marketplace-apis', - 'VTEX - Marketplace APIs - Suggestions': 'marketplace-apis-suggestions', - 'VTEX - Marketplace APIs - Sent Offers': 'marketplace-apis-offer-management', - 'VTEX - Marketplace Protocol - External Marketplace Mapper': - 'marketplace-protocol-external-marketplace-mapper', - 'VTEX - Marketplace Protocol - External Marketplace Orders': - 'marketplace-protocol-external-marketplace-orders', - 'VTEX - Marketplace Protocol - External Seller Fulfillment': - 'marketplace-protocol-external-seller-fulfillment', - 'VTEX - Marketplace Protocol - External Seller Marketplace': - 'marketplace-protocol', - 'VTEX - Master Data API - v2': 'master-data-api-v2', - 'VTEX - MasterData API - v10.2': 'masterdata-api', - 'VTEX - Message Center API': 'message-center-api', - 'VTEX - Orders API PII version': 'orders-api-pii-version', - 'VTEX - Orders API': 'orders-api', - 'VTEX - Payment Provider Protocol': 'payment-provider-protocol', - 'VTEX - Payments Gateway API': 'payments-gateway-api', - 'VTEX - Pick and Pack Last Mile Protocol API': 'pick-and-pack-protocol-api', - 'VTEX - Pick and Pack Order Changes API': 'pick-and-pack-order-changes-api', - 'VTEX - Policies System API': 'policies-system-api', - 'VTEX - Pricing API': 'pricing-api', - 'VTEX - Pricing Hub': 'pricing-hub', - 'VTEX - Profile System': 'profile-system', - 'VTEX - Promotions & Taxes API': 'promotions-and-taxes-api', - 'VTEX - Reviews and Ratings API': 'reviews-and-ratings-api', - 'VTEX - SKU Bindings API': 'sku-bindings-api', - 'VTEX - Search API': 'search-api', - 'VTEX - Session Manager API': 'session-manager-api', - 'VTEX - Subscriptions API v3': 'subscriptions-api-v3', - 'VTEX - Tracking': 'tracking', - 'VTEX - VTEX Do API': 'vtex-do-api', - 'VTEX - VTEX ID API': 'vtex-id-api', - 'VTEX - VTEX Shipping Network API': 'vtex-shipping-network-api', - 'VTEX - Promotions & Taxes API - v2': 'promotions-and-taxes-api-v2', - 'VTEX - Intelligent Search Events API - Headless': - 'intelligent-search-events-api-headless', - 'VTEX - Data Subject Rights': 'data-subject-rights-api', - 'VTEX - Buyer Organizations': 'buyer-organizations', - 'VTEX - Audience API': 'audience-api', - 'VTEX - Ad Network API': 'vtex-ad-network-api', -}) +import { apiSlugMap } from 'utils/api-slug-mapping' + +const referencePaths = objectFlip(apiSlugMap) function objectFlip(obj: { [x: string]: string }) { return Object.keys(obj).reduce((ret, key) => { diff --git a/src/utils/api-slug-mapping.ts b/src/utils/api-slug-mapping.ts new file mode 100644 index 000000000..58ef77e51 --- /dev/null +++ b/src/utils/api-slug-mapping.ts @@ -0,0 +1,62 @@ +/** + * Maps API display names to their corresponding slugs + * This mapping is used for generating reference documentation paths + */ + +export const apiSlugMap: { [key: string]: string } = { + 'VTEX - Antifraud Provider API': 'antifraud-provider-protocol', + 'VTEX - Legacy CMS Portal API': 'legacy-cms-portal-api', + 'VTEX - Catalog API Seller Portal': 'catalog-api-seller-portal', + 'VTEX - Catalog API': 'catalog-api', + 'VTEX - Checkout API': 'checkout-api', + 'VTEX - Checkout Configuration API': 'checkout-configuration-api', + 'VTEX - Customer Credit API': 'customer-credit-api', + 'VTEX - GiftCard Hub API': 'giftcard-hub-api', + 'VTEX - Giftcard API': 'giftcard-api', + 'VTEX - Giftcard Provider Protocol': 'giftcard-provider-protocol', + 'VTEX - Headless CMS API': 'headless-cms-api', + 'VTEX - Intelligent Search API': 'intelligent-search-api', + 'VTEX - License Manager API': 'license-manager-api', + 'VTEX - Logistics API': 'logistics-api', + 'VTEX - Marketplace APIs': 'marketplace-apis', + 'VTEX - Marketplace APIs - Suggestions': 'marketplace-apis-suggestions', + 'VTEX - Marketplace APIs - Sent Offers': 'marketplace-apis-offer-management', + 'VTEX - Marketplace Protocol - External Marketplace Mapper': + 'marketplace-protocol-external-marketplace-mapper', + 'VTEX - Marketplace Protocol - External Marketplace Orders': + 'marketplace-protocol-external-marketplace-orders', + 'VTEX - Marketplace Protocol - External Seller Fulfillment': + 'marketplace-protocol-external-seller-fulfillment', + 'VTEX - Marketplace Protocol - External Seller Marketplace': + 'marketplace-protocol', + 'VTEX - Master Data API - v2': 'master-data-api-v2', + 'VTEX - MasterData API - v10.2': 'masterdata-api', + 'VTEX - Message Center API': 'message-center-api', + 'VTEX - Orders API PII version': 'orders-api-pii-version', + 'VTEX - Orders API': 'orders-api', + 'VTEX - Payment Provider Protocol': 'payment-provider-protocol', + 'VTEX - Payments Gateway API': 'payments-gateway-api', + 'VTEX - Pick and Pack Last Mile Protocol API': 'pick-and-pack-protocol-api', + 'VTEX - Pick and Pack Order Changes API': 'pick-and-pack-order-changes-api', + 'VTEX - Policies System API': 'policies-system-api', + 'VTEX - Pricing API': 'pricing-api', + 'VTEX - Pricing Hub': 'pricing-hub', + 'VTEX - Profile System': 'profile-system', + 'VTEX - Promotions & Taxes API': 'promotions-and-taxes-api', + 'VTEX - Reviews and Ratings API': 'reviews-and-ratings-api', + 'VTEX - SKU Bindings API': 'sku-bindings-api', + 'VTEX - Search API': 'search-api', + 'VTEX - Session Manager API': 'session-manager-api', + 'VTEX - Subscriptions API v3': 'subscriptions-api-v3', + 'VTEX - Tracking': 'tracking', + 'VTEX - VTEX Do API': 'vtex-do-api', + 'VTEX - VTEX ID API': 'vtex-id-api', + 'VTEX - VTEX Shipping Network API': 'vtex-shipping-network-api', + 'VTEX - Promotions & Taxes API - v2': 'promotions-and-taxes-api-v2', + 'VTEX - Intelligent Search Events API - Headless': + 'intelligent-search-events-api-headless', + 'VTEX - Data Subject Rights': 'data-subject-rights-api', + 'VTEX - Buyer Organizations': 'buyer-organizations', + 'VTEX - Audience API': 'audience-api', + 'VTEX - Ad Network API': 'vtex-ad-network-api', +} diff --git a/src/utils/getReferencePaths.ts b/src/utils/getReferencePaths.ts index 1d91ac338..416050ed4 100644 --- a/src/utils/getReferencePaths.ts +++ b/src/utils/getReferencePaths.ts @@ -4,64 +4,7 @@ const referencePaths: { [slug: string]: string } = {} import { getGithubTree } from './github-utils' import { getLogger } from './logging/log-util' import { githubConfig } from './github-config' - -const fileSlugMap: { [key: string]: string } = { - 'VTEX - Antifraud Provider API': 'antifraud-provider-protocol', - 'VTEX - Legacy CMS Portal API': 'legacy-cms-portal-api', - 'VTEX - Catalog API Seller Portal': 'catalog-api-seller-portal', - 'VTEX - Catalog API': 'catalog-api', - 'VTEX - Checkout API': 'checkout-api', - 'VTEX - Checkout Configuration API': 'checkout-configuration-api', - 'VTEX - Customer Credit API': 'customer-credit-api', - 'VTEX - GiftCard Hub API': 'giftcard-hub-api', - 'VTEX - Giftcard API': 'giftcard-api', - 'VTEX - Giftcard Provider Protocol': 'giftcard-provider-protocol', - 'VTEX - Headless CMS API': 'headless-cms-api', - 'VTEX - Intelligent Search API': 'intelligent-search-api', - 'VTEX - License Manager API': 'license-manager-api', - 'VTEX - Logistics API': 'logistics-api', - 'VTEX - Marketplace APIs': 'marketplace-apis', - 'VTEX - Marketplace APIs - Suggestions': 'marketplace-apis-suggestions', - 'VTEX - Marketplace APIs - Sent Offers': 'marketplace-apis-offer-management', - 'VTEX - Marketplace Protocol - External Marketplace Mapper': - 'marketplace-protocol-external-marketplace-mapper', - 'VTEX - Marketplace Protocol - External Marketplace Orders': - 'marketplace-protocol-external-marketplace-orders', - 'VTEX - Marketplace Protocol - External Seller Fulfillment': - 'marketplace-protocol-external-seller-fulfillment', - 'VTEX - Marketplace Protocol - External Seller Marketplace': - 'marketplace-protocol', - 'VTEX - Master Data API - v2': 'master-data-api-v2', - 'VTEX - MasterData API - v10.2': 'masterdata-api', - 'VTEX - Message Center API': 'message-center-api', - 'VTEX - Orders API PII version': 'orders-api-pii-version', - 'VTEX - Orders API': 'orders-api', - 'VTEX - Payment Provider Protocol': 'payment-provider-protocol', - 'VTEX - Payments Gateway API': 'payments-gateway-api', - 'VTEX - Pick and Pack Last Mile Protocol API': 'pick-and-pack-protocol-api', - 'VTEX - Pick and Pack Order Changes API': 'pick-and-pack-order-changes-api', - 'VTEX - Policies System API': 'policies-system-api', - 'VTEX - Pricing API': 'pricing-api', - 'VTEX - Pricing Hub': 'pricing-hub', - 'VTEX - Profile System': 'profile-system', - 'VTEX - Promotions & Taxes API': 'promotions-and-taxes-api', - 'VTEX - Reviews and Ratings API': 'reviews-and-ratings-api', - 'VTEX - SKU Bindings API': 'sku-bindings-api', - 'VTEX - Search API': 'search-api', - 'VTEX - Session Manager API': 'session-manager-api', - 'VTEX - Subscriptions API v3': 'subscriptions-api-v3', - 'VTEX - Tracking': 'tracking', - 'VTEX - VTEX Do API': 'vtex-do-api', - 'VTEX - VTEX ID API': 'vtex-id-api', - 'VTEX - VTEX Shipping Network API': 'vtex-shipping-network-api', - 'VTEX - Promotions & Taxes API - v2': 'promotions-and-taxes-api-v2', - 'VTEX - Intelligent Search Events API - Headless': - 'intelligent-search-events-api-headless', - 'VTEX - Data Subject Rights': 'data-subject-rights-api', - 'VTEX - Buyer Organizations': 'buyer-organizations', - 'VTEX - Audience API': 'audience-api', - 'VTEX - Ad Network API': 'vtex-ad-network-api', -} +import { apiSlugMap } from './api-slug-mapping' export default async function getReferencePaths( branch: string = githubConfig.openapiBranch @@ -87,7 +30,7 @@ export default async function getReferencePaths( : '' if (filetype === 'json' || filetype === 'yaml') { referencePaths[ - fileSlugMap[filename] || filename + apiSlugMap[filename] || filename ] = `https://cdn.jsdelivr.net/gh/vtex/openapi-schemas/${path}` } }