Skip to content

Create API client docs or guide  #4247

Closed
@stevegt

Description

@stevegt
Contributor

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:

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

Activity

added
type/docsThis PR mainly updates/creates documentation
on Jun 15, 2018
daviian

daviian commented on Jun 15, 2018

@daviian
Member

@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

tungsheng commented on Jun 15, 2018

@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

markuman commented on Jun 16, 2018

@markuman

@tungsheng see #4234 (comment)

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

stevegt

stevegt commented on Jun 18, 2018

@stevegt
ContributorAuthor

@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

tungsheng commented on Jun 19, 2018

@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

stevegt commented on Jun 19, 2018

@stevegt
ContributorAuthor

@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

tungsheng commented on Jun 20, 2018

@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

added a commit that references this issue on Jun 24, 2018
d4112d4
stevegt

stevegt commented on Jun 25, 2018

@stevegt
ContributorAuthor

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

tungsheng

tungsheng commented on Jun 25, 2018

@tungsheng

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

added a commit that references this issue on Jun 25, 2018
aaf6be3
locked and limited conversation to collaborators on Nov 24, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    type/docsThis PR mainly updates/creates documentation

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

      Development

      Participants

      @lunny@stevegt@tungsheng@markuman@daviian

      Issue actions

        Create API client docs or guide · Issue #4247 · go-gitea/gitea