Add owner and parent fields clarification to docs

[AlexMaryW]

Issue: #9637

Changes introduced: I have clarified the problematic terms (owner and parent) in all affected endpoints.

The changes were made to relevant:

• HTTP endpoint parameters' descriptions
• response/request models' fields

This MR is big, but most changes are the same. If you'd like me to break this MR into several smaller ones, let me know :)

[techknowlogick]

Amazing, thanks!

[wxiaoguang]

Most changes are:

- //   description: owner of the repo
+ //   description: username of the user or organization owning the repository

IMO "owner" is already a widely used concept, we can explain it somewhere, and keep the old description. Old description looks clearer

[AlexMaryW]

Most changes are:

- //   description: owner of the repo
+ //   description: username of the user or organization owning the repository

IMO "owner" is already a widely used concept, we can explain it somewhere, and keep the old description. Old description looks clearer

Thanks for reviewing the MR! :)

• A new Gitea user might not be familiar with the owner concept and then the old description sounds confusing (as flagged in this issue).
• It's considered good practice to think of API docs as reference material. Hence, we should provide all necessary information in every single endpoint instead of explaining all concepts only once or assuming prior knowledge.
• The owner definition in the regular Gitea docs (the only definition I could find) does not match the API definition of the owner. For example, the regular docs state that a user or several of them can be owners of the repo and it is true of the Gitea UI. On the other hand, the API does not allow for many users to own a repo; it can either be a user or an org and the API considers both as the same object. If someone new to the concept reads the regular docs and then goes on to use the API, their understanding of owner will not be correct.
• If the definitions of owner for UI and API differ, we cannot explain the concept in the regular docs and must use the API docs. From my point of view, there isn't a better place to define this concept than in every affected endpoint. How else can we ensure that the definition is easy to find and that every user will have the correct understanding of the concept?

[wxiaoguang]

I would still suggest to avoid repeating the "owner" explanation hundreds of times.

Could you revert these changes? We can do it better by adding a "Concept" table on the UI, explain everything one time at one place.

[AlexMaryW]

Sure, your approach makes sense. I reverted the changes, could you please take another look?

Could you please elaborate on the 'Concept' table in the UI? I don't understand where you'd like to put it (e.g. under the "This documentation describes the Gitea API" or outside of the API docs?). I'd be happy to write it if possible.

[wxiaoguang]

Thank you very much. Will make some more changes, IMO:

• It doesn't need to explain the "owner" if it is used as "repo.owner" or "repo_owner_name", the variable name is already clear enough.
• IssueMeta.Owner is "owner of the issue's repo" (but not "owner of the issue")
• Added a TODO in "swagger/ui.tmpl": add Help & Glossary to help users understand the API, and explain some concepts like "Owner"