Correct swagger annotations for enums, status codes, and notification state

[myers]

⚠️ BREAKING ⚠️

• delete reaction endpoints is changed to return 204 No Content rather than 200 with no content.

Summary

Add swagger:enum annotations and migrate all enum comments from the deprecated comma-separated format to JSON arrays. Introduce NotifySubjectStateType with open/closed/merged values. Fix delete reaction endpoints to return 204 instead of 200.

This is one part of a stacked set. The other adds a OpenAPI 3 spec generated off of the swagger spec. With these corrections it is good enough to have OpenAPI 3 code generating tools (like rust's https://github.com/oxidecomputer/progenitor) to create API clients based off of it.

This was built in Claude Code, with human review.

[wxiaoguang]

This change seems good.

---

For the plan (https://github.com/myers/gitea/tree/feat/openapi3-conversion, especially the commit myers@14d2832), I recalled some discussions for this topic:

• Replace go-swagger with huma #33685

(als cc @TheFox0x7 🙏 )

[TheFox0x7]

+1 from me. I don't see anything wrong with this.

[TheFox0x7]

As for the v3; I don't mind generating v3 from v2 if you want to send that too. Though I'd rather generate v2 from v3 and get rid of generating spec from comments as - as you can see - it's not accurate at times, there are not examples etc.
Generating this form I/O structs like huma does it would be better but integrating that would take a while (especially to review later).

I won't even suggest writing spec first and generating server from that as I don't want to do it myself :)

[wxiaoguang]

For "v3", some questions in my mind:

• Should it co-exist with v2?
  • If yes, what are the use cases?
  • If no, we can just keep one and remove the other.
• Is it really good enough to generate v3 from v2? Need to think about bad cases
  • If good enough, we can still generate v3 from v2
  • If there are bad cases and would cause problems, well, need some new plans

[myers]

For "v3", some questions in my mind:

* Should it co-exist with v2?

It does

  * If yes, what are the use cases?

To allow tools that use openapi 3 specs to generate api clients.

  * If no, we can just keep one and remove the other.

Sounds like a breaking change! ;). The v3 spec is generated from the v2 spec.

* Is it really good enough to generate v3 from v2? Need to think about bad cases

Yes it is good enough, at least for the one library I tried (see PR description). I have tried Fern for python as well, which correctly created the client, but I didn't get a chance to test it yet.

  * If good enough, we can still generate v3 from v2
  * If there are bad cases and would cause problems, well, need some new plans

You can take a peek at it https://github.com/myers/gitea/tree/feat/openapi3-conversion

BTW: I 100% recommend going with spec first API, this was just trying to deliver a feature I needed without rocking the boat too much.

[TheFox0x7]

Should it co-exist with v2?

There are still generators that consume v2 only. Though for every language you'll find one that does v3 only so it cuts both ways. I'd drop v2 but we'd have to have native generation first which swagger does not provide

BTW: I 100% recommend going with spec first API, this was just trying to deliver a feature I needed without rocking the boat too much.

I don't see a way for this here. AFAIK you'd have to rework entire api, plus I very much doubt anyone here wants to write yaml/json instead of go. And sure, you could write spec in go, serialize it to yaml, then generate server.

[wxiaoguang]

Maybe we can leave the discussion to the future.

By the way, actually our framework has the ability to fully manage the route endpoints, much better than chi (example: Refactor auth middleware #36848)

So maybe now it is feasible to do something like huma (or use huma as the base framework and we call it after we have parsed our routes)

[wxiaoguang]

By the way, I removed the "breaking" label.

I doubt whether there are really many people using "delete reaction endpoint" and would be really affected.

To prevent from frightening most unrelated users, I think this PR doesn't need to be marked as "breaking"