From 6a27fbeddab4e6b54fbe135a99b96e694aa701dd Mon Sep 17 00:00:00 2001
From: Tim Riedl <mail@tim-riedl.de>
Date: Sun, 20 Apr 2025 17:05:12 +0200
Subject: [PATCH] Add Swagger documentation for OAuth2 authentication endpoints

---
 routers/api/v1/admin/auth_oauth.go | 113 ++++++++++++++++++++++++++++-
 1 file changed, 112 insertions(+), 1 deletion(-)

diff --git a/routers/api/v1/admin/auth_oauth.go b/routers/api/v1/admin/auth_oauth.go
index 21a4215eb7..bd7bc0b4fc 100644
--- a/routers/api/v1/admin/auth_oauth.go
+++ b/routers/api/v1/admin/auth_oauth.go
@@ -22,6 +22,29 @@ import (
 
 // CreateOauthAuth create a new external authentication for oauth2
 func CreateOauthAuth(ctx *context.APIContext) {
+	// swagger:operation PUT /admin/identity-auth/oauth admin adminCreateOauth2Auth
+	// ---
+	// summary: Create an OAuth2 authentication source
+	// consumes:
+	// - application/json
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: body
+	//   in: body
+	//   required: true
+	//   schema:
+	//     "$ref": "#/definitions/CreateAuthOauth2Option"
+	// responses:
+	//   "201":
+	//     description: OAuth2 authentication source created successfully
+	//   "400":
+	//     "$ref": "#/responses/error"
+	//   "403":
+	//     "$ref": "#/responses/forbidden"
+	//   "422":
+	//     "$ref": "#/responses/validationError"
+
 	form := web.GetForm(ctx).(*api.CreateAuthOauth2Option)
 
 	discoveryURL, err := url.Parse(form.ProviderAutoDiscoveryURL)
@@ -66,12 +89,54 @@ func CreateOauthAuth(ctx *context.APIContext) {
 
 // EditOauthAuth api for modifying a authentication method
 func EditOauthAuth(ctx *context.APIContext) {
+	// swagger:operation PATCH /admin/identity-auth/oauth/{id} admin adminEditOauth2Auth
+	// ---
+	// summary: Update an OAuth2 authentication source
+	// consumes:
+	// - application/json
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: id
+	//   in: path
+	//   description: authentication source ID
+	//   type: integer
+	//   format: int64
+	//   required: true
+	// - name: body
+	//   in: body
+	//   required: true
+	//   schema:
+	//     "$ref": "#/definitions/CreateAuthOauth2Option"
+	// responses:
+	//   "201":
+	//     description: OAuth2 authentication source updated successfully
+	//   "400":
+	//     "$ref": "#/responses/error"
+	//   "403":
+	//     "$ref": "#/responses/forbidden"
+	//   "404":
+	//     "$ref": "#/responses/notFound"
+	//   "422":
+	//     "$ref": "#/responses/validationError"
+
 	oauthIDString := ctx.PathParam("id")
 	oauthID, oauthIDErr := strconv.Atoi(oauthIDString)
 	if oauthIDErr != nil {
 		ctx.APIErrorInternal(oauthIDErr)
 	}
 
+	source, sourceErr := auth_model.GetSourceByID(ctx, int64(oauthID))
+	if sourceErr != nil {
+		ctx.APIErrorInternal(sourceErr)
+		return
+	}
+
+	if source.Type != auth_model.OAuth2 {
+		ctx.APIErrorNotFound()
+		return
+	}
+
 	form := web.GetForm(ctx).(*api.CreateAuthOauth2Option)
 
 	config := &oauth2.Source{
@@ -111,6 +176,28 @@ func EditOauthAuth(ctx *context.APIContext) {
 
 // DeleteOauthAuth api for deleting a authentication method
 func DeleteOauthAuth(ctx *context.APIContext) {
+	// swagger:operation DELETE /admin/identity-auth/oauth/{id} admin adminDeleteOauth2Auth
+	// ---
+	// summary: Delete an OAuth2 authentication source
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: id
+	//   in: path
+	//   description: authentication source ID
+	//   type: integer
+	//   format: int64
+	//   required: true
+	// responses:
+	//   "200":
+	//     description: OAuth2 authentication source deleted successfully
+	//   "403":
+	//     "$ref": "#/responses/forbidden"
+	//   "404":
+	//     "$ref": "#/responses/notFound"
+	//   "422":
+	//     "$ref": "#/responses/validationError"
+
 	oauthIDString := ctx.PathParam("id")
 	oauthID, oauthIDErr := strconv.Atoi(oauthIDString)
 	if oauthIDErr != nil {
@@ -137,8 +224,32 @@ func DeleteOauthAuth(ctx *context.APIContext) {
 	ctx.Status(http.StatusOK)
 }
 
-// // SearchOauthAuth API for getting information of the configured authentication methods according the filter conditions
+// SearchOauthAuth API for getting information of the configured authentication methods according the filter conditions
 func SearchOauthAuth(ctx *context.APIContext) {
+	// swagger:operation GET /admin/identity-auth/oauth admin adminSearchOauth2Auth
+	// ---
+	// summary: Search OAuth2 authentication sources
+	// produces:
+	// - application/json
+	// parameters:
+	// - name: page
+	//   in: query
+	//   description: page number of results to return (1-based)
+	//   type: integer
+	// - name: limit
+	//   in: query
+	//   description: page size of results
+	//   type: integer
+	// responses:
+	//   "200":
+	//     description: "SearchResults of OAuth2 authentication sources"
+	//     schema:
+	//       type: array
+	//       items:
+	//         "$ref": "#/definitions/AuthOauth2Option"
+	//   "403":
+	//     "$ref": "#/responses/forbidden"
+
 	listOptions := utils.GetListOptions(ctx)
 
 	authSources, maxResults, err := db.FindAndCount[auth_model.Source](ctx, auth_model.FindSourcesOptions{})