Expand OpenAPI spec + MCP tooling for org-governance endpoints (#727 series) #738

New Issue

2026-07-05T06:23:58Z

jmiller commented

2026-07-05 06:23:58 +00:00

Context

The org-governance series (#728–#732, all merged to dev) added five org-level API surfaces under /orgs/{org}/:

Endpoint	Verbs	Handler
`/branch_protections`	List, Create, Get, Edit, Delete	`routers/api/v1/org/branch_protection.go`
`/tag_protections`	List, Create, Get, Edit, Delete	`routers/api/v1/org/tag_protection.go`
`/push_policy`	Get, Edit, Delete (singleton)	`routers/api/v1/org/push_policy.go`
`/repo_defaults`	Get, Edit, Delete (singleton)	`routers/api/v1/org/repo_defaults.go`
`/email_domain_policy`	Get, Edit, Delete (singleton)	`routers/api/v1/org/email_domain.go`

Routes, handlers, and DTOs (modules/structs/org_*.go) are all in place and the code compiles/vets clean locally. But the handlers carry zero swagger annotations, so none of these endpoints appear in the generated OpenAPI spec (templates/swagger/v1_json.tmpl). They are functional but undocumented and undiscoverable.

Why this gates the `dev → main` release (#733)

A stable main release should not ship an undocumented API surface. Downstream API clients, generated SDKs, and the MCP server all derive from the OpenAPI spec — an un-annotated endpoint effectively doesn't exist for them.

Scope

A. OpenAPI annotations + regen — blocks #733 merge to main

Add // swagger:operation doc-comments to all handlers in routers/api/v1/org/{branch_protection,tag_protection,push_policy,repo_defaults,email_domain}.go (params, body, responses, error codes).
Register // swagger:response models for the new response types in routers/api/v1/swagger/.
Add // swagger:parameters where the Edit*/Create* option DTOs are used as request bodies.
Regenerate templates/swagger/v1_json.tmpl via the swagger generator (now possible — Go toolchain available locally at A:\programs\go).
Verify: go build ./... clean, spec validates, endpoints render in /api/swagger.

B. MCP tooling — follows A (tracked here, does not block the merge)

Add MCP tools to mcp-mokogitea-api for the new org endpoints: gitea_org_branch_protection_*, gitea_org_tag_protection_*, gitea_org_push_policy_*, gitea_org_repo_defaults_*, gitea_org_email_domain_policy_*.
Wire them into the tool registry + schemas; publish a new npm version.

C. Repo-facing read views — follow-up (does not block)

Read-only "inherited org rules" views for push-policy + repo-defaults in repo settings (branch/tag protection views already exist from #728/#729).

Sequence

A → merge #733 to main → B → C. This issue tracks all three; A is the immediate blocker.

Related: #727 (parent), #728, #729, #730, #731, #732, #733 (release PR).

https://claude.ai/code/session_01Wsno14cxE49MstXFs9G5KT

## Context The org-governance series (#728–#732, all merged to `dev`) added five org-level API surfaces under `/orgs/{org}/`: | Endpoint | Verbs | Handler | |---|---|---| | `/branch_protections` | List, Create, Get, Edit, Delete | `routers/api/v1/org/branch_protection.go` | | `/tag_protections` | List, Create, Get, Edit, Delete | `routers/api/v1/org/tag_protection.go` | | `/push_policy` | Get, Edit, Delete (singleton) | `routers/api/v1/org/push_policy.go` | | `/repo_defaults` | Get, Edit, Delete (singleton) | `routers/api/v1/org/repo_defaults.go` | | `/email_domain_policy` | Get, Edit, Delete (singleton) | `routers/api/v1/org/email_domain.go` | Routes, handlers, and DTOs (`modules/structs/org_*.go`) are all in place and the code compiles/vets clean locally. **But the handlers carry zero swagger annotations**, so none of these endpoints appear in the generated OpenAPI spec (`templates/swagger/v1_json.tmpl`). They are functional but undocumented and undiscoverable. ## Why this gates the `dev → main` release (#733) A stable `main` release should not ship an undocumented API surface. Downstream API clients, generated SDKs, and the MCP server all derive from the OpenAPI spec — an un-annotated endpoint effectively doesn't exist for them. ## Scope ### A. OpenAPI annotations + regen — **blocks #733 merge to main** - [ ] Add `// swagger:operation` doc-comments to all handlers in `routers/api/v1/org/{branch_protection,tag_protection,push_policy,repo_defaults,email_domain}.go` (params, body, responses, error codes). - [ ] Register `// swagger:response` models for the new response types in `routers/api/v1/swagger/`. - [ ] Add `// swagger:parameters` where the `Edit*`/`Create*` option DTOs are used as request bodies. - [ ] Regenerate `templates/swagger/v1_json.tmpl` via the swagger generator (now possible — Go toolchain available locally at `A:\programs\go`). - [ ] Verify: `go build ./...` clean, spec validates, endpoints render in `/api/swagger`. ### B. MCP tooling — follows A (tracked here, does not block the merge) - [ ] Add MCP tools to `mcp-mokogitea-api` for the new org endpoints: `gitea_org_branch_protection_*`, `gitea_org_tag_protection_*`, `gitea_org_push_policy_*`, `gitea_org_repo_defaults_*`, `gitea_org_email_domain_policy_*`. - [ ] Wire them into the tool registry + schemas; publish a new npm version. ### C. Repo-facing read views — follow-up (does not block) - [ ] Read-only "inherited org rules" views for push-policy + repo-defaults in repo settings (branch/tag protection views already exist from #728/#729). ## Sequence A → merge #733 to main → B → C. This issue tracks all three; A is the immediate blocker. Related: #727 (parent), #728, #729, #730, #731, #732, #733 (release PR). https://claude.ai/code/session_01Wsno14cxE49MstXFs9G5KT

jmiller commented

2026-07-05 06:24:05 +00:00

Branch created: feature/738-expand-openapi-spec-mcp-tooling-for-org-

git fetch origin
git checkout feature/738-expand-openapi-spec-mcp-tooling-for-org-

Branch created: [`feature/738-expand-openapi-spec-mcp-tooling-for-org-`](https://git.mokoconsulting.tech/MokoConsulting/MokoGitea-Fork/src/branch/feature/738-expand-openapi-spec-mcp-tooling-for-org-) ```bash git fetch origin git checkout feature/738-expand-openapi-spec-mcp-tooling-for-org- ```

jmiller referenced this issue from a commit

2026-07-05 07:01:04 +00:00

docs(api): swagger annotations + response models for org-governance endpoints (#727, #738)

jmiller referenced this issue

2026-07-05 07:01:31 +00:00

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

jmiller referenced this issue from a commit

2026-07-05 15:19:23 +00:00

Merge pull request 'docs(api): OpenAPI spec + README/CHANGELOG for org-governance (#727, #738)' (#739) from feat/org-governance-openapi into dev

jmiller referenced this issue

2026-07-05 15:38:18 +00:00

Release: org-wide governance series (#727) — dev → main #733