From d13f68a5b43c662b53607569ca6cf99a32c0905b Mon Sep 17 00:00:00 2001 From: Tarek Lokal Date: Sat, 11 Jul 2026 17:47:36 +0200 Subject: [PATCH] docs: clarify canonical API documentation sources (#2057) Mark goadmin.ifrc.org/docs as canonical and ifrcgo.org how-to page as deprecated; add maintainer migration checklist. Co-authored-by: Cursor --- docs/api-documentation-sources.md | 42 +++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) create mode 100644 docs/api-documentation-sources.md diff --git a/docs/api-documentation-sources.md b/docs/api-documentation-sources.md new file mode 100644 index 000000000..0b96f9f33 --- /dev/null +++ b/docs/api-documentation-sources.md @@ -0,0 +1,42 @@ +# GO API documentation sources + +This note clarifies which API documentation sources are **canonical** for IFRCGo/go-api and which legacy pages should be treated as deprecated. + +Related: [IFRCGo/go-api#770](https://github.com/IFRCGo/go-api/issues/770), [#2057](https://github.com/IFRCGo/go-api/issues/2057). + +## Canonical (maintained) + +Use these as the source of truth for API consumers and contributors: + +| Source | URL | Purpose | +|--------|-----|---------| +| **Swagger / OpenAPI (production)** | https://goadmin.ifrc.org/docs/ | Interactive API reference for deployed GO API | +| **GO Wiki** | Linked from Swagger and project README | Broader GO platform documentation | +| **Repository README** | [`README.md`](../README.md) | Setup, development, and links to other docs | + +When adding or changing endpoints, update OpenAPI schema generation and ensure Swagger reflects the change after deploy. + +## Deprecated / legacy + +| Source | URL | Status | +|--------|-----|--------| +| **Legacy how-to page** | https://ifrcgo.org/how-to-use-the-go-api/ | **Deprecated** — not cross-linked from canonical docs; content may be stale. Prefer [goadmin.ifrc.org/docs](https://goadmin.ifrc.org/docs/). | + +### Recommended action for maintainers + +1. Add a banner on the legacy ifrcgo.org page pointing to https://goadmin.ifrc.org/docs/ +2. Migrate any unique content from the legacy page into the wiki or Swagger descriptions +3. Remove or redirect the legacy URL when traffic drops + +## Contributor checklist + +- [ ] New public endpoints documented in OpenAPI / Swagger +- [ ] README links to canonical Swagger URL +- [ ] Do not add new documentation only on legacy ifrcgo.org pages + +## In-repo documentation + +| Document | Topic | +|----------|-------| +| [`docs/montandon-external-token-jwt.md`](./montandon-external-token-jwt.md) | Montandon / external token JWT flow | +| [`CONTRIBUTING.md`](../CONTRIBUTING.md) | Development setup (when present on default branch) |