MokoConsulting/MokoGitea-Fork
1
0
Fork 0
Code Issues 129 Pull Requests 2 Releases 96 Wiki Activity

docs(api): OpenAPI spec + README/CHANGELOG for org-governance (#727, #738) #739

Open
jmiller wants to merge 2 commits from feat/org-governance-openapi into dev
pull from: feat/org-governance-openapi
merge into: :dev
Conversation 0 Commits 2 Files Changed 11
+5608 -14
jmiller commented 2026-07-05 07:01:31 +00:00
Owner
Copy Link
Copy Source

Completes the documentation/OpenAPI surface for the org-governance series (#728–#732) so the stable main release (#733) ships a fully-described API. Resolves scope A of #738 (the item that gated the merge to main).

OpenAPI / swagger (the gating work)

The five org-governance API groups were functional but undocumented — the four later handlers had zero swagger annotations and no swagger:response models were registered (even the existing branch_protection.go $ref'd responses that were never defined). Now:

  • 7 swagger:response models registered in routers/api/v1/swagger/org.go: OrgBranchProtection/OrgBranchProtectionList, OrgTagProtection/OrgTagProtectionList, and singletons OrgPushPolicy, OrgRepoDefaults, OrgEmailDomainPolicy.
  • 14 operations annotated across tag_protection.go (5), push_policy.go (3), repo_defaults.go (3), email_domain.go (3) — styled exactly like the existing branch_protection.go, unique operationIds, org path param, body $refs to the correct DTOs, #/responses/empty for 204, notFound/validationError. No handler logic changed (annotations only).
  • Spec regenerated: both templates/swagger/v1_json.tmpl and v1_openapi3_json.tmpl.

Pre-existing spec blockers fixed as a prerequisite

The committed spec was stale and could not be regenerated at all. To produce a valid spec (no logic changes):

  • manifest.go: removed a stray comment glued to the repoUpdateManifest swagger block (broke YAML parsing), added missing owner/repo path params, registered a Manifest response, gofmt whitespace.
  • options.go: registered the org option DTOs + pre-existing unregistered defs (EditAccessTokenOption, IssueBulk*Option, Issue{Priority,Status,Type}Def) so there are no dangling $refs.

Docs

  • README: added an Org Governance key-feature entry + broadened the tagline.
  • CHANGELOG [Unreleased]: recorded the recent build/CI fixes (#734, #735, #736, #737). (The org-governance features were already listed.)

Verification (local, Go 1.26.3)

  • go build ./... → clean (only tests/integration, which is pre-existing-broken, excluded)
  • gofmt -l on all edited .go files → clean
  • swagger validate → valid against Swagger 2.0 (benign unused-response warnings only)
  • Dangling-ref scan → 0 missing definitions/responses
  • Confirmed all 4 new endpoint groups + all 14 operationIds present in v1_json.tmpl

Related: #738 (tracker; B = MCP tools and C = repo-facing views remain), #727, #733.

https://claude.ai/code/session_01Wsno14cxE49MstXFs9G5KT

Completes the documentation/OpenAPI surface for the org-governance series (#728–#732) so the stable `main` release (#733) ships a fully-described API. Resolves scope **A** of #738 (the item that gated the merge to main). ## OpenAPI / swagger (the gating work) The five org-governance API groups were functional but **undocumented** — the four later handlers had zero swagger annotations and no `swagger:response` models were registered (even the existing `branch_protection.go` `$ref`'d responses that were never defined). Now: - **7 `swagger:response` models** registered in `routers/api/v1/swagger/org.go`: `OrgBranchProtection`/`OrgBranchProtectionList`, `OrgTagProtection`/`OrgTagProtectionList`, and singletons `OrgPushPolicy`, `OrgRepoDefaults`, `OrgEmailDomainPolicy`. - **14 operations annotated** across `tag_protection.go` (5), `push_policy.go` (3), `repo_defaults.go` (3), `email_domain.go` (3) — styled exactly like the existing `branch_protection.go`, unique operationIds, `org` path param, body `$ref`s to the correct DTOs, `#/responses/empty` for 204, `notFound`/`validationError`. **No handler logic changed** (annotations only). - **Spec regenerated**: both `templates/swagger/v1_json.tmpl` and `v1_openapi3_json.tmpl`. ### Pre-existing spec blockers fixed as a prerequisite The committed spec was stale and could not be regenerated at all. To produce a *valid* spec (no logic changes): - `manifest.go`: removed a stray comment glued to the `repoUpdateManifest` swagger block (broke YAML parsing), added missing `owner`/`repo` path params, registered a `Manifest` response, gofmt whitespace. - `options.go`: registered the org option DTOs + pre-existing unregistered defs (`EditAccessTokenOption`, `IssueBulk*Option`, `Issue{Priority,Status,Type}Def`) so there are no dangling `$ref`s. ## Docs - **README**: added an **Org Governance** key-feature entry + broadened the tagline. - **CHANGELOG** `[Unreleased]`: recorded the recent build/CI fixes (#734, #735, #736, #737). (The org-governance features were already listed.) ## Verification (local, Go 1.26.3) - `go build ./...` → **clean** (only `tests/integration`, which is pre-existing-broken, excluded) - `gofmt -l` on all edited `.go` files → clean - `swagger validate` → valid against Swagger 2.0 (benign unused-response warnings only) - Dangling-ref scan → 0 missing definitions/responses - Confirmed all 4 new endpoint groups + all 14 operationIds present in `v1_json.tmpl` Related: #738 (tracker; B = MCP tools and C = repo-facing views remain), #727, #733. https://claude.ai/code/session_01Wsno14cxE49MstXFs9G5KT
jmiller added 2 commits 2026-07-05 07:01:32 +00:00
docs: README org-governance feature + CHANGELOG CI fixes (#727) 81ea2fcb05 
Add an Org Governance entry to the README key-features list (org-wide
branch/tag protection, push policy, repo defaults, email-domain
allowlist) and record the recent build/CI fixes (#734, #735, #736,
#737) under CHANGELOG [Unreleased].

Claude-Session: https://claude.ai/code/session_01Wsno14cxE49MstXFs9G5KT
docs(api): swagger annotations + response models for org-governance endpoints (#727, #738)
Universal: PR Check / Branch Policy (pull_request) Successful in 1s
Details
PR RC Release / Build RC Release (pull_request) Successful in 3s
Details
Universal: PR Check / Validate PR (pull_request) Successful in 11s
Details
Generic: Project CI / Lint & Validate (pull_request) Successful in 41s
Details
Universal: PR Check / Secret Scan (pull_request) Successful in 59s
Details
Generic: Project CI / Tests (pull_request) Has been cancelled
Details
Universal: PR Check / Build RC Package (pull_request) Has been cancelled
Details
Universal: PR Check / Report Issues (pull_request) Has been cancelled
Details
93365cdd95 
Annotate the four previously undocumented org-governance API handlers
(tag_protection, push_policy, repo_defaults, email_domain) with
swagger:operation blocks, and register the swagger:response models the
branch_protection operations already referenced. Register the org
option DTOs in the parameterBodies hack so their definitions are
emitted.

Also fix pre-existing spec-generation blockers surfaced once the spec
became regenerable: a stray comment glued to the repoUpdateManifest
swagger block (broke YAML parsing), missing owner/repo path params on
the manifest operations, a Manifest response registration, and missing
definitions for EditAccessTokenOption, the IssueBulk* options, and the
Issue{Priority,Status,Type}Def types. Regenerated v1_json.tmpl and
v1_openapi3_json.tmpl; spec now validates cleanly against Swagger 2.0.

Claude-Session: https://claude.ai/code/session_01Wsno14cxE49MstXFs9G5KT
Some required checks failed
Universal: PR Check / Branch Policy (pull_request) Successful in 1s
Details
PR RC Release / Build RC Release (pull_request) Successful in 3s
Details
Universal: PR Check / Validate PR (pull_request) Successful in 11s
Details
Generic: Project CI / Lint & Validate (pull_request) Successful in 41s
Details
Universal: PR Check / Secret Scan (pull_request) Successful in 59s
Details
Generic: Project CI / Tests (pull_request) Has been cancelled
Details
Universal: PR Check / Build RC Package (pull_request) Has been cancelled
Details
Universal: PR Check / Report Issues (pull_request) Has been cancelled
Details
You are not authorized to merge this pull request.
This pull request can be merged automatically.
View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u origin feat/org-governance-openapi:feat/org-governance-openapi
git checkout feat/org-governance-openapi
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
Clear labels
breaking-change
Breaking API or behavior change
 ci-cd
CI/CD pipeline changes
 config
Configuration changes
 dependencies
Dependency updates
 deploy-failure
Deployment failed
 docker
Docker/container changes
 documentation
Documentation changes
 feature: wiki
Wiki system enhancements
 good first issue
Good for newcomers
 health-check
Repo health check result
 help wanted
Extra attention needed
 mokostandards
Related to MokoStandards framework
 push-failure
Git push operation failed
 security
Security vulnerability or hardening
 size/l
200-500 lines changed
 size/m
50-200 lines changed
 size/s
10-50 lines changed
 size/xl
500+ lines changed
 size/xs
< 10 lines changed
 standards-drift
Deviates from MokoStandards
 standards-update
MokoStandards compliance update
 sync-failure
Sync or mirror failed
 tech-debt
Technical debt and TODO/FIXME items
 upstream
upstream
Inherited from upstream Gitea
 work-in-progress
Draft or incomplete work
bug
Something is not working
 duplicate
This issue or pull request already exists
 enhancement
New feature
 help wanted
Need some help
 invalid
Something is wrong
 question
More information is needed
 wontfix
This won't be fixed
No labels
Priority -
Type -
Milestone
No items
No Milestone
Assignees
Clear assignees
jmiller (Jonathan Miller) moko-deploy (Moko Deploy Bot)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: MokoConsulting/MokoGitea-Fork#739
Delete Branch "feat/org-governance-openapi"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?