Documentation: API path parameter naming

[HoffmannP]

• Gitea version (or commit ref): 1.5

Description

All the path parameters in swagger (POST & GET are counted as one occurence)
45 {repo}
44 {owner}
22 {id}
20 {username}
12 {org}
8 {index}
2 {filepath}
1 {user}
1 {token}
1 {sha}
1 {ref}
1 {follower}
1 {followee}
1 {collaborator}
1 {branch}
1 {attachment_id}
1 {archive}

(jq -r '.paths | keys' swagger.v1.json | grep -o '\{[^\}]*\}' | sort | uniq -c | sort -rn)

As you can see there are 22 id and 8 index path parameter occurences in the swagger file. Most other parameters are distinctive and understandable form the first look. I'd recommend to rename these parameters to something easily understandable.

Just one example:

/repos/{owner}/{repo}/milestones/{id}
Get a milestone

rename the parameter:
{id} -> {milestone_id} (see attachment_id)
changing the description:
"id of the milestone" -> "id as obtainable from /repos/{owner}/{repo}/milestones"

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs during the next 2 weeks. Thank you for your contributions.

[stale]

This issue has been automatically closed because of inactivity. You can re-open it if needed.

[6543]

@HoffmannP I find {id} more elegant and smalrer than {milestone_id} and the URL path determine its meaning so if path is .../milestone/{id} its very likely that the id is a milestone_id ?

I personaly would go the other way and would rename {attachment_id} to {id} so it follows pattern ...

[zeripath]

The trouble is the swagger API is presented in multiple different formats, but most often without the URL to accompany it. In which case, the only context you have is the method name and parameter names. I can easily imagine that using id might be confusing in that situation.