OSPI Docs

Documentation portal for OSPI (Open Standard Product Identification), built with Docusaurus.

Platform source · Report an issue

Table of Contents

• About the Project
  • Built With
• Getting Started
  • Prerequisites
  • Installation
• Content structure
• Contributing
• License

About The Project

This is the documentation site for OSPI (Open Standard Product Identification) — an open standard and API platform for product identity, master data, and cross-organization product data exchange. It documents the real, running reference implementation at ospi-platform: guides and a full REST API reference.

All content is sourced from the actual ospi-platform codebase (controllers, DTOs, ADRs, domain docs) — not invented. Where the platform has an open question or a "not built yet," the docs say so.

Built With

• Docusaurus
• React
• Tailwind CSS

Getting Started

Prerequisites

• Node.js ≥ 18
• npm

Installation

git clone https://github.com/BrickeVD/OSPI-APIdocs.git
cd OSPI-APIdocs
npm install
npm start

Content structure

The site is two separate Docusaurus doc instances, defined in docusaurus.config.js:

Instance	Path	Route	Content
guides	docs/guides	/guides	Introduction, quickstart, authentication, core concepts, errors, idempotency/rate limits, webhooks, roles
api-reference	docs/api-reference	/api-reference	Hand-written domain guides (Guides) + a live, generated per-endpoint reference with request/response schemas and a "Try It" console (Endpoints)

There is deliberately no Architecture Decision Records section — ADRs live in ospi-platform/docs/adr if you need the internal design rationale, but this site stays focused on how to use the API.

Branding (src/css/custom.css, static/logo/) uses a placeholder pink wordmark — the real OSPI logo and full brand guidelines were not available at the time this site was built; swap static/logo/light.svg and static/logo/dark.svg once they are.

Regenerating the API Reference (Endpoints) from the real backend

The Endpoints pages under /api-reference are not hand-written — they're generated by docusaurus-plugin-openapi-docs from openapi/ospi-platform.json, a real OpenAPI 3 document exported from the actual ospi-platform NestJS backend's own SwaggerModule (the same document it serves at /api/docs-json), not written by hand — filtered by scripts/filter-openapi.js before it reaches this site (see below). To refresh it after the backend's API surface changes:

# In a clone of ospi-platform, with Postgres + Redis reachable per its own README:
npx ts-node -T scripts/generate-openapi.ts    # writes openapi.json (see that script; not committed there)

# Back in this repo:
cp path/to/ospi-platform/openapi.json openapi/ospi-platform.raw.json
node scripts/filter-openapi.js                # writes the filtered openapi/ospi-platform.json
npm run gen-api-docs                          # regenerates docs/api-reference/reference/**
npm run build                                 # verify

scripts/generate-openapi.ts boots the real Nest application (so Postgres/Redis must be reachable) and dumps SwaggerModule.createDocument(...) to disk instead of calling app.listen(). It lives in ospi-platform, not here — it's a one-off export script for that backend, not a doc-site build step.

What scripts/filter-openapi.js changes, and why

openapi/ospi-platform.raw.json is kept as the untouched export — full fidelity to the backend, in case a future decision needs it. openapi/ospi-platform.json (the one actually consumed by gen-api-docs) is a derived, public-facing copy:

• Drops the admin and unspsc tags entirely (operations + any schema that becomes unreferenced as a result). Both are real backend routes, but neither is a third-party integration surface: admin is platform-operator-only account management, and unspsc is an internal catalog-import tool. Excluding them here doesn't change what the backend actually exposes — only what this public API reference documents.
• Strips ADR citations ((ADR-016), ADR-053: …, see ADR-030, etc.) out of every description and summary. The backend's Swagger decorators cite ADRs for its own engineering audience; this site has no Architecture section for those citations to point to, so they're just noise for API consumers.

Contributing

See CONTRIBUTING.md and CODE_OF_CONDUCT.md.

License

Distributed under the Apache License, Version 2.0. See LICENSE for more information.