API documentation inconsistencies

[ederuiter]

• Gitea version (or commit ref): 1.10
• Git version: n/a
• Operating system: n/a
• Database: n/a
• Test url: https://try.gitea.io/api/swagger

Description

When working with the API I came across a number of documentation inconsistencies:

• all API calls for users refer to {username} .. however looking at the fields of a user there is no username field, only login. More confusingly creating a new user does list the username field but it also lists the login_name field but not the login field

• all API calls for repos refer to {owner} .. a repository does have an owner, but in this case the {owner} can also refer to an org, so maybe we should refer to this as {parent} .. but the api documentation for the Models lists the parent field, but not its type.

• all API calls for repos refer to {repo} .. is this the name or the id? This is not clear from the docs

• I was going to mention that the responses/body are only represented by example values .. but it turns out you can click on "model" to get the definition .. this is nice, but not very obvious from the UI (I only found out when writing this issue).

None of these issues are showstoppers for working with the API .. but it increases the number of wtf's per minute greatly when first working with the API

[6543]

all API calls for repos refer to {repo}

= the name

[stale]

This issue has been automatically marked as stale because it has not had recent activity. I am here to help clear issues left open even if solved or waiting for more insight. This issue will be closed if no further activity occurs during the next 2 weeks. If the issue is still valid just add a comment to keep it alive. Thank you for your contributions.