API documentation for endpoint
joubertredrat opened this issue · 33 comments
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.
I also dislike the Wiki approach, the docs have to be bundled with the code and also exported automatically to the docs website.
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
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.
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
Nobody wants to do it twice, so we should directly provide something generated out of swagger annotations
Yes, we need an API document ASAP.
We could use : https://goswagger.io/generate/spec.html ?
Until there is a proper API documentation available. Where can I dig around to find out how to call the api?
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)
Hi,
Is there a swagger document available as of now? I need to generate a client in c#.
@SeanFarrow it is still WIP - https://try.gitea.io/swagger
Thanks, Do you know whether there are any test servers available, or alternatively a vagrant/packer base box. I'm tryingot write integration tests against the API.
There is https://try.gitea.io but integration tests for api are run localy from development environment (see https://github.com/go-gitea/gitea/tree/master/integrations)
On linux you need to run make test-pgsql or make test-mysql but you need postgresql or mysql set up correctly
Hi,
Assuming I have a url for a server, what is the uri for the api?
I've had a look at api.go and only see gitea.io url's.
Help appreciated.
Kind regards
Sean.
You could try to go to /swagger on your instance to view documentation and you could use integration test has an example for url, like :
gitea/integrations/api_issue_test.go
Line 25 in f1adaef
Hi all,
What is the minimum version of Gitea that the api works with, with v1.1.0, the API doesn't seem to exist, I'm only getting 404's and no swagger document exists at /swagger as noted above.
Any help appreciated.
Cheers
Sean.
@SeanFarrow /swagger is the document which is on v1.2. But the APIs works well on v1.1.0
@SeanFarrow If you haven't got this to work yet, here's an example https://try.gitea.io/api/v1/repos/search?q=gitea
This one could be close
@sapk https://try.gitea.io/ seems to be down
@marbetschar yes, we are changing to a new plan for bigger disk space.
@lunny meanwhile, is there any documentation for the api available? We are working on a Gitea integration, but its not so easy getting things right by solely read the code in the repo.
@marbetschar I just uploaded at https://app.swaggerhub.com/apis/gitea/gitea-api/1.1.1 you can see it there for the moment. I will need to auto-update that if we keep it.
You can always copy https://raw.githubusercontent.com/go-gitea/gitea/master/public/swagger.v1.json to https://editor.swagger.io/ (File -> Import URL)
@sapk thanks for this! I can see a bunch of errors there (screenshot attached), but I guess I can ignore them for now?
@marbetschar yes, we need to fill security schema and maybe other spec to be fully compliant with swagger and the editor seems to be more exigent than the swagger-ui we use in gitea. But with all the definitions allready done you should get enough information to get started with api. You can dismiss error and hide them even.