andrewmusselman opened a new pull request, #1261: URL: https://github.com/apache/tooling-trusted-releases/pull/1261
## Summary Adds `atr/docs/api-documentation-policy.md` as developer-guide section **3.16**, and renumbers `ASFQuart usage` to 3.17. The new page records, as formal documentation, the policy that `/api/openapi.json` and `/api/docs` are intentionally public. Also fixes a pre-existing typo: section 3.10 (Code policies) was written as `3.10` (no trailing period) in five places. All now read `3.10.` to match the convention used by every other section number. Closes #1056. ## Why The decision to keep the OpenAPI spec and Swagger UI public was already made and reflected as an inline `audit_guidance` comment in `atr/server.py` (`_app_setup_api_docs`). @dave2wave asked for formal documentation of the rationale ([comment](https://github.com/apache/tooling-trusted-releases/issues/1056#issuecomment-)) so the ASVS 13.4.5 (L2) control has a documented policy and not just a code comment. @dave2wave's follow-up specified: - filename `atr/docs/api-documentation-policy.md` - "Look at the adjacent md files and create the correct header and linkage" - "to be section 3.16" ## What's in the new page - **Decision** — the policy in one sentence - **Rationale** — public API, ASF open-source practice, admin surface filtered by `ApiOnlyOpenAPIProvider`, and the fact that documenting an endpoint does not bypass its auth - **What the public spec contains / does not contain** — explicit lists so auditors can see the boundary - **Endpoint-level authentication is unchanged** — points at `3.12. Authentication security` and the `/api` blueprint rate limit - **ASVS reference** — explicit link to ASVS v5 §13.4.5 (L2) and how each requirement is met - **Implementation references** — `server.py`, `blueprints/api.py`, `jwtoken.py`, `templates/about.html` The page header, navigation links (Up / Prev / Next), and section list follow the same convention as the adjacent docs (`tls-security-configuration.md`, `asfquart-usage.md`, `authentication-security.md`). ## TOC and Prev/Next chain Inserted at 3.16; ASFQuart usage shifts to 3.17. All four affected files are kept consistent: | File | Change | | ----------------------------------- | ------------------------------------------------------- | | `atr/docs/api-documentation-policy.md` | **New file** — section 3.16 | | `atr/docs/index.md` | Inserted 3.16 entry, ASFQuart shifted to 3.17 | | `atr/docs/developer-guide.md` | Same — its "Pages" list | | `atr/docs/tls-security-configuration.md` | `**Next**` → API documentation policy | | `atr/docs/asfquart-usage.md` | Renumbered to 3.17, `**Prev**` → API documentation policy | ## Typo fix included While here, fixed the missing period after `3.10` (Code policies) in all five places it appears: | File | Where | | --------------------------------- | ---------------------- | | `atr/docs/code-policies.md` | Page heading | | `atr/docs/index.md` | Top-level TOC | | `atr/docs/developer-guide.md` | "Pages" list | | `atr/docs/code-conventions.md` | **Next** link | | `atr/docs/how-to-contribute.md` | **Prev** link | Every other section number in the docs uses the `N.M.` form; 3.10 was the only outlier. ## What this PR does not change - No code changes. The inline `audit_guidance` comment in `atr/server.py` stays; this page is the policy record it implicitly references. - `atr/templates/about.html` line 52 (the `/api/docs` link from the About page) is left as-is. The triage's open question about adding a "requires authentication for actual use" note is not addressed here; that's a UX call separate from the policy decision and worth a follow-up issue if wanted. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
