gitea

gitea copied to clipboard

Feature Description

GitLab has a feature where they can render openapi/swagger documents using swagger-ui in a rendered view. We should consider adding this too as we already bundle swagger-ui, so it's a almost-zero cost addition.

GitLab can render OpenAPI specification files. The filename must include openapi or swagger and the extension must be yaml, yml, or json

Yes, it would be nice! I am currently trying to switch to Gitea from Gitlab and this has been missing from my list

Since iframe will be introduced in #20180, this becomes possible.

Probably good to iframe it, yes.

Thought, we could also do without backend support and just create the iframe in JS, like already done for mermaid:

https://github.com/go-gitea/gitea/blob/bf325d44120c4a6fc7f67ff1dc25db770247c9a7/web_src/js/markup/mermaid.js#L55

While swagger ui would not introduce new dependencies I would rather see redoc being used for this as looks way better and readable

I find swagger-ui more readable than redoc, but that's probably because I'm used to it. To me, swagger-ui is still kind of the gold standard for openapi specs.

According to https://www.wappalyzer.com/compare/redoc-vs-swagger-ui, swagger ui is more than 12 times more popular than redoc.

I agree for swagger ui being better when you want it to be deployed with API where you can try it etc but in this case when it's only documentation display redoc has multiple advantages over swagger-ui like better display on mobile devices, easier to read nested structure documentation, better support for openapi 3 (like oneof that swagger-ui does not even support etc)