Create API client docs or guide

[stevegt]

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:

gitea/modules/auth/auth.go

Line 47 in 6efdcae

if len(auths) == 2 && auths[0] == "token" {

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. ;-)

[daviian]

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

[tungsheng]

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

[markuman]

@tungsheng see #4234 (comment)

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

[stevegt]

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

[tungsheng]

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

[stevegt]

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

[tungsheng]

@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

[stevegt]

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

[tungsheng]

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