Update swagger documentation (#2899)

* Update swagger documentation

Add docs for missing endpoints
Add documentation for request parameters
Make parameter naming consistent
Fix response documentation

* Restore delete comments

3 files changed, 123 insertions, 84 deletions

diff --git a/routers/api/v1/admin/org.go b/routers/api/v1/admin/org.go
index 99c9cf0b95..d247b51c72 100644
--- a/routers/api/v1/admin/org.go
+++ b/routers/api/v1/admin/org.go
@@ -15,20 +15,26 @@ import (
 
 // CreateOrg api for create organization
 func CreateOrg(ctx *context.APIContext, form api.CreateOrgOption) {
-	// swagger:route POST /admin/users/{username}/orgs admin adminCreateOrg
-	//
-	//     Consumes:
-	//     - application/json
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       201: Organization
-	//       403: forbidden
-	//       422: validationError
-	//       500: error
-
+	// swagger:operation POST /admin/users/{username}/orgs admin adminCreateOrg
+	// ---
+	// summary: Create an organization
+	// consumes:
+	// - application/json
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: username
+	//   in: path
+	//   description: username of the user that will own the created organization
+	//   type: string
+	//   required: true
+	// responses:
+	//   "201":
+	//     "$ref": "#/responses/Organization"
+	//   "403":
+	//     "$ref": "#/responses/forbidden"
+	//   "422":
+	//     "$ref": "#/responses/validationError"
 	u := user.GetUserByParams(ctx)
 	if ctx.Written() {
 		return
diff --git a/routers/api/v1/admin/repo.go b/routers/api/v1/admin/repo.go
index 232fb988c8..70765557fb 100644
--- a/routers/api/v1/admin/repo.go
+++ b/routers/api/v1/admin/repo.go
@@ -14,20 +14,26 @@ import (
 
 // CreateRepo api for creating a repository
 func CreateRepo(ctx *context.APIContext, form api.CreateRepoOption) {
-	// swagger:route POST /admin/users/{username}/repos admin adminCreateRepo
-	//
-	//     Consumes:
-	//     - application/json
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       201: Repository
-	//       403: forbidden
-	//       422: validationError
-	//       500: error
-
+	// swagger:operation POST /admin/users/{username}/repos admin adminCreateRepo
+	// ---
+	// summary: Create a repository on behalf a user
+	// consumes:
+	// - application/json
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: username
+	//   in: path
+	//   description: username of the user. This user will own the created repository
+	//   type: string
+	//   required: true
+	// responses:
+	//   "201":
+	//     "$ref": "#/responses/Repository"
+	//   "403":
+	//     "$ref": "#/responses/forbidden"
+	//   "422":
+	//     "$ref": "#/responses/validationError"
 	owner := user.GetUserByParams(ctx)
 	if ctx.Written() {
 		return
diff --git a/routers/api/v1/admin/user.go b/routers/api/v1/admin/user.go
index 74cbba8cde..19f24aed8f 100644
--- a/routers/api/v1/admin/user.go
+++ b/routers/api/v1/admin/user.go
@@ -5,13 +5,12 @@
 package admin
 
 import (
-	api "code.gitea.io/sdk/gitea"
-
 	"code.gitea.io/gitea/models"
 	"code.gitea.io/gitea/modules/context"
 	"code.gitea.io/gitea/modules/log"
 	"code.gitea.io/gitea/modules/setting"
 	"code.gitea.io/gitea/routers/api/v1/user"
+	api "code.gitea.io/sdk/gitea"
 )
 
 func parseLoginSource(ctx *context.APIContext, u *models.User, sourceID int64, loginName string) {
@@ -34,22 +33,27 @@ func parseLoginSource(ctx *context.APIContext, u *models.User, sourceID int64, l
 	u.LoginName = loginName
 }
 
-// CreateUser api for creating a user
+// CreateUser create a user
 func CreateUser(ctx *context.APIContext, form api.CreateUserOption) {
-	// swagger:route POST /admin/users admin adminCreateUser
-	//
-	//     Consumes:
-	//     - application/json
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       201: User
-	//       403: forbidden
-	//       422: validationError
-	//       500: error
-
+	// swagger:operation POST /admin/users admin adminCreateUser
+	// ---
+	// summary: Create a user
+	// consumes:
+	// - application/json
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: body
+	//   in: body
+	//   schema:
+	//     "$ref": "#/definitions/CreateUserOption"
+	// responses:
+	//   "201":
+	//     "$ref": "#/responses/User"
+	//   "403":
+	//     "$ref": "#/responses/forbidden"
+	//   "422":
+	//     "$ref": "#/responses/validationError"
 	u := &models.User{
 		Name:      form.Username,
 		FullName:  form.FullName,
@@ -87,20 +91,30 @@ func CreateUser(ctx *context.APIContext, form api.CreateUserOption) {
 
 // EditUser api for modifying a user's information
 func EditUser(ctx *context.APIContext, form api.EditUserOption) {
-	// swagger:route PATCH /admin/users/{username} admin adminEditUser
-	//
-	//     Consumes:
-	//     - application/json
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       200: User
-	//       403: forbidden
-	//       422: validationError
-	//       500: error
-
+	// swagger:operation PATCH /admin/users/{username} admin adminEditUser
+	// ---
+	// summary: Edit an existing user
+	// consumes:
+	// - application/json
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: username
+	//   in: path
+	//   description: username of user to edit
+	//   type: string
+	//   required: true
+	// - name: body
+	//   in: body
+	//   schema:
+	//     "$ref": "#/definitions/EditUserOption"
+	// responses:
+	//   "200":
+	//     "$ref": "#/responses/User"
+	//   "403":
+	//     "$ref": "#/responses/forbidden"
+	//   "422":
+	//     "$ref": "#/responses/validationError"
 	u := user.GetUserByParams(ctx)
 	if ctx.Written() {
 		return
@@ -157,17 +171,24 @@ func EditUser(ctx *context.APIContext, form api.EditUserOption) {
 
 // DeleteUser api for deleting a user
 func DeleteUser(ctx *context.APIContext) {
-	// swagger:route DELETE /admin/users/{username} admin adminDeleteUser
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       204: empty
-	//       403: forbidden
-	//       422: validationError
-	//       500: error
-
+	// swagger:operation DELETE /admin/users/{username} admin adminDeleteUser
+	// ---
+	// summary: Delete a user
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: username
+	//   in: path
+	//   description: username of user to delete
+	//   type: string
+	//   required: true
+	// responses:
+	//   "204":
+	//     "$ref": "#/responses/empty"
+	//   "403":
+	//     "$ref": "#/responses/forbidden"
+	//   "422":
+	//     "$ref": "#/responses/validationError"
 	u := user.GetUserByParams(ctx)
 	if ctx.Written() {
 		return
@@ -189,20 +210,26 @@ func DeleteUser(ctx *context.APIContext) {
 
 // CreatePublicKey api for creating a public key to a user
 func CreatePublicKey(ctx *context.APIContext, form api.CreateKeyOption) {
-	// swagger:route POST /admin/users/{username}/keys admin adminCreatePublicKey
-	//
-	//     Consumes:
-	//     - application/json
-	//
-	//     Produces:
-	//     - application/json
-	//
-	//     Responses:
-	//       201: PublicKey
-	//       403: forbidden
-	//       422: validationError
-	//       500: error
-
+	// swagger:operation POST /admin/users/{username}/keys admin adminCreatePublicKey
+	// ---
+	// summary: Add a public key on behalf of a user
+	// consumes:
+	// - application/json
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: username
+	//   in: path
+	//   description: username of the user
+	//   type: string
+	//   required: true
+	// responses:
+	//   "201":
+	//     "$ref": "#/responses/PublicKey"
+	//   "403":
+	//     "$ref": "#/responses/forbidden"
+	//   "422":
+	//     "$ref": "#/responses/validationError"
 	u := user.GetUserByParams(ctx)
 	if ctx.Written() {
 		return