API documentation for endpoint

[joubertredrat]

Hi guys,

I think that a important thing on Gitea is have a API endpoint documentation on application or on site documentation like Swagger or Apidoc.
With this will be more easy to see all methods (or operations) and all information about each one of them.

Today on Gogs, this documentation is on github wiki and isn't easy to learn and work with this.

---

Want to back this issue? Post a bounty on it! We accept bounties via Bountysource.

[tboerger]

I also dislike the Wiki approach, the docs have to be bundled with the code and also exported automatically to the docs website.

[bkcsoft]

I started to play around with swagger[1] today, IMO it would be the best solution (even though I personally prefer ApiDoc...). I'm just not entirely sure how/where we should present it, @tboerger had the idea of integrating the docs in Gitea itself (e.g. try.gitea.io/docs/api ) though I'm not sure that is a good idea

[1] https://github.com/yvasiyarov/swagger

[tboerger]

We can enable or disable that via config flag. Additionally to that we can extract this documentation from every branch and provide all of this within our docs or at a separate page.

[joubertredrat]

For first I think that is good idea to documentation manually on https://api.gitea.io/ as example because today doesn't exists anything about API documentation

After this we can view automated tools like Swagger

[tboerger]

Nobody wants to do it twice, so we should directly provide something generated out of swagger annotations

[lunny]

Yes, we need an API document ASAP.

[sapk]

We could use : https://goswagger.io/generate/spec.html ?

[ralphtheninja]

Until there is a proper API documentation available. Where can I dig around to find out how to call the api?

[sapk]

You could find all api url in code here : https://github.com/go-gitea/gitea/blob/master/routers/api/v1/api.go#L230

You could copy-paste : https://github.com/sapk-fork/gitea/blob/generate-swagger/public/swagger.v1.json in http://editor.swagger.io for viewing incoming documentation.

You could also look at https://github.com/go-gitea/go-sdk that is a go package to access the api (all url are not implemented)

[SeanFarrow]

Hi,
Is there a swagger document available as of now? I need to generate a client in c#.