> For the complete documentation index, see [llms.txt](https://developers.share.inc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.share.inc/readme.md).

# Share Public API

This directory is the source for the public-facing API documentation site at [`developers.share.inc`](https://developers.share.inc). It is bidirectionally synced with a GitBook space via GitBook's Git Sync GitHub App.

## Sync convention

**Git is the source of truth.** Engineers edit Markdown in PRs against `staging`; releases roll forward to `main` on the existing share-api cadence.

GitBook's Git Sync is bidirectional:

* **Engineer / Git path:** edit Markdown in `docs-site/` directly in a PR.
* **Content contributor / GUI path:** edit in the GitBook web editor; GitBook commits the change back to the repo as `gitbook-com[bot]`.

GUI edits land as `gitbook-com[bot]` commits directly on the synced branch (no PR review). Treat each GUI save as effectively a commit — expect the change to surface in `git log`. If a contributor wants review on a content change, route them through the Git path (open a PR) instead of the GUI.

> The GUI-edit commit policy (direct push vs. auto-PR) is configured at the GitBook-space level by whoever owns the GitBook org. The current setting is **direct push** — update this paragraph if the policy changes.

## OpenAPI reference (`openapi/share-api.json`)

The OpenAPI 3 document is generated from the NestJS Swagger decorators on `apps/api/src/v1/**`. It is **committed as a build artifact** (like the Prisma client) so GitBook can render it without running TypeScript.

### Refreshing the spec

After any change to a Swagger decorator (`@ApiProperty`, `@ApiOperation`, `@ApiResponse`, new controller, new DTO, etc.) — or any new endpoint — run:

```bash
npm run docs:openapi
```

This boots the Nest API gateway in "dump" mode, builds the OpenAPI document, sorts keys deterministically, and writes `docs-site/openapi/share-api.json`. Commit the refreshed artifact alongside your code change.

### CI freshness guard

`.github/workflows/docs-validate.yml` re-runs `npm run docs:openapi` on every PR that touches `apps/api/**` or `docs-site/**`. If the committed JSON is stale, the workflow fails with `git diff --exit-code` and blocks the merge. This guarantees the published reference can never drift from the live decorators.

Decorator coverage (query DTO `@ApiProperty`s, custom-header declarations, per-tag descriptions, per-operation error codes) and the public error contract / catalog landed under DEV-853.

## Docs change flow

```
Engineer edits @ApiProperty in apps/api/src/v1/.../dto.ts
        │
        ▼
Runs `npm run docs:openapi` locally
        │
        ▼
Commits the DTO change + refreshed docs-site/openapi/share-api.json
        │
        ▼
Opens PR targeting `staging`
        │
        ├─► docs-validate.yml passes (artifact is fresh)
        ├─► pr-build.yml passes
        │
        ▼
PR merged → staging → main (existing release cadence)
        │
        ▼
GitBook detects the commit on the synced branch via webhook
        │
        ▼
GitBook pulls `docs-site/`, re-renders the space
        │
        ▼
developers.share.inc reflects the new content within ~1 minute
```

## Rollback

Docs rollback uses normal Git — there is no special procedure.

```bash
git revert <commit-sha>          # revert on the synced branch
git push origin <synced-branch>  # GitBook re-syncs in ~1 minute
```

Either revert on `main` (immediate effect on `developers.share.inc`) or on `staging` (then promote on the next release).

## Branch strategy

| Git branch | GitBook variant    | Public URL                     |
| ---------- | ------------------ | ------------------------------ |
| `main`     | Production         | `developers.share.inc`         |
| `staging`  | Draft (if enabled) | `staging.developers.share.inc` |

The draft variant depends on GitBook tier support. If unavailable, only the production variant is wired up and `staging.developers.share.inc` is not provisioned.

## Adding a page

1. Create the Markdown file under the right group (e.g. `guides/refund-flow.md`)
2. Add an entry to `SUMMARY.md` (page order + grouping)
3. Cross-link from related pages (use relative links, e.g. `[Errors](../errors/README.md)`)
4. Open a PR against `staging`

## Embedding an OpenAPI operation inside a guide

GitBook's OpenAPI block can embed a single operation by `operationId`:

```markdown
{% openapi-operation src="openapi/share-api.json" operationId="SubscribersController_create" %}
{% endopenapi-operation %}
```

This keeps tutorials grounded in the live spec — when the decorator changes, the embedded block updates on the next docs PR. See [`guides/onboard-a-subscriber.md`](/guides/onboard-a-subscriber.md) for a worked example.

## Mermaid diagrams

GitBook renders fenced `mermaid` blocks natively. No plugin needed.

````markdown
```mermaid
sequenceDiagram
  Partner->>Share: POST /v1/subscribers
  Share-->>Partner: 201 Created
```
````

## Internal vs. published

The Swagger UI at `/docs` and `/docs/v1` on the Nest gateway is kept as an internal-dev convenience. Sunset is tracked as a follow-up cleanup ticket once partners are on this site.