Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

API documentation for endpoint #194

Closed
joubertredrat opened this issue Nov 18, 2016 · 33 comments
Closed

API documentation for endpoint #194

joubertredrat opened this issue Nov 18, 2016 · 33 comments
Labels
type/docs This PR mainly updates/creates documentation

Comments

@joubertredrat
Copy link
Contributor

joubertredrat commented Nov 18, 2016 •
edited by bkcsoft
Loading

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.
@lunny lunny added the type/docs This PR mainly updates/creates documentation label Nov 20, 2016
@lunny lunny added this to the 1.x.x milestone Nov 20, 2016
@tboerger
Copy link
Member

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

@bkcsoft
Copy link
Member

bkcsoft commented Dec 26, 2016

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
Copy link
Member

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
Copy link
Contributor Author

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
Copy link
Member

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

@lunny
Copy link
Member

lunny commented Dec 27, 2016

Yes, we need an API document ASAP.

@lunny lunny mentioned this issue Feb 23, 2017
Open
20 tasks
@sapk
Copy link
Member

sapk commented Mar 28, 2017

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

@sapk sapk mentioned this issue Mar 28, 2017
Merged
39 tasks
@ralphtheninja
Copy link

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

@sapk
Copy link
Member

sapk commented Apr 24, 2017 •
edited
Loading

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)

ethantkoenig pushed a commit to ethantkoenig/gitea that referenced this issue Jul 10, 2017
@richmahn
Feature - Issue 181 - Changes Door43 to DCS and adds images (go-gitea…
8ddba7e 
…#194)

* Changes Door43 to DCS and adds images

* Updates favicon.png to a 143x143 image
@SeanFarrow
Copy link

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

@lafriks
Copy link
Member

lafriks commented Jul 18, 2017

@SeanFarrow it is still WIP - https://try.gitea.io/swagger

@SeanFarrow
Copy link

SeanFarrow commented Jul 18, 2017 via email

@SeanFarrow
Copy link

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.

@lafriks
Copy link
Member

lafriks commented Jul 19, 2017

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)

@SeanFarrow
Copy link

SeanFarrow commented Jul 19, 2017 via email

@lafriks
Copy link
Member

lafriks commented Jul 19, 2017

On linux you need to run make test-pgsql or make test-mysql but you need postgresql or mysql set up correctly

@SeanFarrow
Copy link

SeanFarrow commented Jul 19, 2017 via email

@SeanFarrow
Copy link

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.

@sapk
Copy link
Member

sapk commented Jul 25, 2017 •
edited
Loading

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

req := NewRequestf(t, "GET", "/api/v1/repos/%s/%s/issues?state=all",

@SeanFarrow
Copy link

SeanFarrow commented Jul 25, 2017 via email

@SeanFarrow
Copy link

SeanFarrow commented Jul 27, 2017 via email

@SeanFarrow
Copy link

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.

@lunny
Copy link
Member

lunny commented Aug 1, 2017

@SeanFarrow /swagger is the document which is on v1.2. But the APIs works well on v1.1.0

@SeanFarrow
Copy link

SeanFarrow commented Aug 1, 2017 via email

@cez81
Copy link
Contributor

cez81 commented Sep 11, 2017

@SeanFarrow If you haven't got this to work yet, here's an example https://try.gitea.io/api/v1/repos/search?q=gitea

@sapk
Copy link
Member

sapk commented Dec 15, 2017

This one could be close

@lunny lunny removed this from the 1.x.x milestone Dec 15, 2017
@lunny
Copy link
Member

lunny commented Dec 15, 2017

@sapk I think yes.

@lunny lunny closed this as completed Dec 15, 2017
@marbetschar
Copy link

@sapk https://try.gitea.io/ seems to be down

@lunny
Copy link
Member

lunny commented Mar 14, 2018

@marbetschar yes, we are changing to a new plan for bigger disk space.

@marbetschar
Copy link

marbetschar commented Mar 15, 2018 •
edited
Loading

@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.

@sapk
Copy link
Member

sapk commented Mar 15, 2018

@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)

@marbetschar
Copy link

@sapk thanks for this! I can see a bunch of errors there (screenshot attached), but I guess I can ignore them for now?

bildschirmfoto 2018-03-15 um 11 53 13

@marbetschar marbetschar mentioned this issue Mar 15, 2018
Closed
@sapk
Copy link
Member

sapk commented Mar 15, 2018

@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.

@UziTech UziTech mentioned this issue Mar 16, 2018
Closed
7 tasks
@go-gitea go-gitea locked and limited conversation to collaborators Nov 24, 2020
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees
No one assigned
Labels
type/docs This PR mainly updates/creates documentation
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
10 participants
@lunny @tboerger @lafriks @ralphtheninja @marbetschar @SeanFarrow @joubertredrat @sapk @bkcsoft @cez81