Create API client docs or guide #1935

New Issue

GiteaMirror · 2025-11-02T04:18:12-06:00

GiteaMirror commented

2025-11-02 04:18:12 -06:00

Originally created by @stevegt on GitHub (Jun 14, 2018).

We need some API client docs. This would be a place to list gitea-compatible swagger or openapi client libraries, gitea-specific clients, and client developer docs, hints, tips, or suggestions.

As an example use case, I just now spent the last 24 hours trying to get the Authorization: header to work from an openapi client. I wound up duplicating #3673 with #4243, but only after grepping around and finally finding this: 6efdcaed86/modules/auth/auth.go (L47) For lack of any better place to put it, I've put a mini-HOWTO into the comments of #4243. A google search right now for site:docs.gitea.io authorization turns up nothing relevant.

I'm assuming client docs or guides should go into the ./docs tree. If there are no objections, I'll start a single page for now, e.g. ./docs/content/doc/advanced/api.XXX.md, later promoting to ./docs/content/doc/api/* as the content accumulates.

Pinging @daviian because #4037 provided most of the API docs we have so far. ;-)

Originally created by @stevegt on GitHub (Jun 14, 2018). We need some API client docs. This would be a place to list gitea-compatible swagger or openapi client libraries, gitea-specific clients, and client developer docs, hints, tips, or suggestions. As an example use case, I just now spent the last 24 hours trying to get the `Authorization:` header to work from an openapi client. I wound up duplicating #3673 with #4243, but only after grepping around and finally finding this: https://github.com/go-gitea/gitea/blob/6efdcaed86565c91a3dc77631372a9cc45a58e89/modules/auth/auth.go#L47 For lack of any better place to put it, I've put a mini-HOWTO into the comments of #4243. A google search right now for `site:docs.gitea.io authorization` turns up nothing relevant. I'm assuming client docs or guides should go into the ./docs tree. If there are no objections, I'll start a single page for now, e.g. ./docs/content/doc/advanced/api.XXX.md, later promoting to ./docs/content/doc/api/* as the content accumulates. Pinging @daviian because #4037 provided most of the API docs we have so far. ;-)

GiteaMirror added the type/docs label 2025-11-02 04:18:12 -06:00

GiteaMirror closed this issue

2025-11-02 04:18:12 -06:00

GiteaMirror commented

2025-11-02 04:18:13 -06:00

@daviian commented on GitHub (Jun 15, 2018):

@stevegt I don't have any complaints about creating a lot more documentation! Unfortunately we don't shine with our documentation 😄

You are right, documentation go under docs/content/doc/...
I'd suggest to put documentation that describes how to use the gitea frontend under a new folder user-guides and create an api-authentication.md file.
To enable the new User Guide subsection you've to create the user-guide.en-us.md - compare with the other subsections.

@daviian commented on GitHub (Jun 15, 2018): @stevegt I don't have any complaints about creating a lot more documentation! Unfortunately we don't shine with our documentation 😄 You are right, documentation go under `docs/content/doc/...` I'd suggest to put documentation that describes how to use the gitea frontend under a new folder `user-guides` and create an `api-authentication.md` file. To enable the new `User Guide` subsection you've to create the `user-guide.en-us.md` - compare with the other subsections.

GiteaMirror commented

2025-11-02 04:18:13 -06:00

@tungsheng commented on GitHub (Jun 15, 2018):

@stevegt I am new to gitea project, and I'd love to help working on the API doc. Any sugestion on how to start?

@tungsheng commented on GitHub (Jun 15, 2018): @stevegt I am new to gitea project, and I'd love to help working on the API doc. Any sugestion on how to start?

GiteaMirror commented

2025-11-02 04:18:13 -06:00

@markuman commented on GitHub (Jun 16, 2018):

@tungsheng see https://github.com/go-gitea/gitea/issues/4234#issuecomment-397789976

the swagger specification for /users/{username}/tokens is wrong.

@markuman commented on GitHub (Jun 16, 2018): @tungsheng see https://github.com/go-gitea/gitea/issues/4234#issuecomment-397789976 the swagger specification for `/users/{username}/tokens` is wrong.

GiteaMirror commented

2025-11-02 04:18:13 -06:00

@stevegt commented on GitHub (Jun 18, 2018):

@tungsheng I should get a chance to start the API doc files this week; I'll ping you once I have them started. In the meantime, take a look at https://github.com/go-gitea/gitea/blob/master/CONTRIBUTING.md if you haven't already.

@stevegt commented on GitHub (Jun 18, 2018): @tungsheng I should get a chance to start the API doc files this week; I'll ping you once I have them started. In the meantime, take a look at https://github.com/go-gitea/gitea/blob/master/CONTRIBUTING.md if you haven't already.

GiteaMirror commented

2025-11-02 04:18:13 -06:00

@tungsheng commented on GitHub (Jun 19, 2018):

@stevegt I have done a simple start following suggestions by @markuman and @daviian, how do I let you or people review and give advice for a branch in my gitea fork? PR? Thank you for helping me start contributing!

@tungsheng commented on GitHub (Jun 19, 2018): @stevegt I have done a simple start following suggestions by @markuman and @daviian, how do I let you or people review and give advice for a branch in my gitea fork? PR? Thank you for helping me start contributing!

GiteaMirror commented

2025-11-02 04:18:13 -06:00

@stevegt commented on GitHub (Jun 19, 2018):

@tungsheng If you're not yet sure that your branch is ready for a PR, you can push your branch to your fork on github and then, in an issue comment, provide a link to your commit for discussion.

@stevegt commented on GitHub (Jun 19, 2018): @tungsheng If you're not yet sure that your branch is ready for a PR, you can push your branch to your fork on github and then, in an issue comment, provide a link to your commit for discussion.

GiteaMirror commented

2025-11-02 04:18:14 -06:00

@tungsheng commented on GitHub (Jun 20, 2018):

@stevegt here are the commits in my branch, I have tested locally. Please advise on how to improve it further.
https://github.com/tungsheng/gitea/commits/feature/user_guides_doc

@tungsheng commented on GitHub (Jun 20, 2018): @stevegt here are the commits in my branch, I have tested locally. Please advise on how to improve it further. https://github.com/tungsheng/gitea/commits/feature/user_guides_doc

GiteaMirror commented

2025-11-02 04:18:14 -06:00

@stevegt commented on GitHub (Jun 25, 2018):

@tungsheng Thank you for getting that started! I've migrated in additional content and submitted as PR #4306.

@stevegt commented on GitHub (Jun 25, 2018): @tungsheng Thank you for getting that started! I've migrated in additional content and submitted as PR #4306.

GiteaMirror commented

2025-11-02 04:18:14 -06:00

@tungsheng commented on GitHub (Jun 25, 2018):

@stevegt Awesome!! Thank you for helping me learn to contribute!

@tungsheng commented on GitHub (Jun 25, 2018): @stevegt Awesome!! Thank you for helping me learn to contribute!

GiteaMirror referenced this issue

2025-11-02 12:03:01 -06:00

[PR #1935] [CLOSED] Fix parsing of received environment variables from SSH clients #16132

GiteaMirror referenced this issue

2025-11-02 12:32:15 -06:00

[PR #4266] [CLOSED] Remove environment variable parsing from SSH server #17309

Sign in to join this conversation.