Description
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:
Line 47 in 6efdcae
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. ;-)
Activity
daviian commentedon 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 anapi-authentication.md
file.To enable the new
User Guide
subsection you've to create theuser-guide.en-us.md
- compare with the other subsections.tungsheng commentedon 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?
markuman commentedon Jun 16, 2018
@tungsheng see #4234 (comment)
the swagger specification for
/users/{username}/tokens
is wrong.stevegt commentedon 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.
tungsheng commentedon 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!
stevegt commentedon 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.
tungsheng commentedon 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
flesh out API usage docs
stevegt commentedon Jun 25, 2018
@tungsheng Thank you for getting that started! I've migrated in additional content and submitted as PR #4306.
tungsheng commentedon Jun 25, 2018
@stevegt Awesome!! Thank you for helping me learn to contribute!
Create api-usage doc page (#4306)