From 95e34a1ed31c2e7f5b6a75509ea02e4fa96b758a Mon Sep 17 00:00:00 2001 From: Pierre-Olivier Mercier Date: Sun, 16 Nov 2025 11:44:26 +0700 Subject: [PATCH] Add missing API documentation --- internal/api/controller/authentication.go | 37 +++++++++++++++++++++++ internal/api/controller/domain.go | 18 ++++++++++- internal/api/controller/service_specs.go | 2 +- internal/api/controller/user.go | 15 +++++++++ internal/api/controller/zone.go | 15 +++++++++ 5 files changed, 85 insertions(+), 2 deletions(-) diff --git a/internal/api/controller/authentication.go b/internal/api/controller/authentication.go index a499c3f8..880c0eca 100644 --- a/internal/api/controller/authentication.go +++ b/internal/api/controller/authentication.go @@ -43,10 +43,35 @@ func NewLoginController(authService happydns.AuthenticationUsecase) *LoginContro } } +// getLoggedUser retrieves the currently logged-in user. +// +// @Summary Get the current user. +// @Schemes +// @Description Retrieve information about the currently logged-in user. +// @Tags authentication +// @Accept json +// @Produce json +// @Security securitydefinitions.basic +// @Success 200 {object} happydns.User +// @Failure 401 {object} happydns.ErrorResponse "Authentication failure" +// @Router /auth/user [get] func (lc *LoginController) GetLoggedUser(c *gin.Context) { c.JSON(http.StatusOK, c.MustGet("LoggedUser")) } +// login authenticates a user with username and password. +// +// @Summary Log in a user. +// @Schemes +// @Description Authenticate a user with email and password, creating a new session. +// @Tags authentication +// @Accept json +// @Produce json +// @Param body body happydns.LoginRequest true "Login credentials" +// @Success 200 {object} happydns.User +// @Failure 400 {object} happydns.ErrorResponse "Invalid input" +// @Failure 401 {object} happydns.ErrorResponse "Invalid username or password" +// @Router /auth/login [post] func (lc *LoginController) Login(c *gin.Context) { var request happydns.LoginRequest @@ -69,6 +94,18 @@ func (lc *LoginController) Login(c *gin.Context) { c.JSON(http.StatusOK, user) } +// logout clears the current user's session. +// +// @Summary Log out the current user. +// @Schemes +// @Description Clear the current user's session and log them out. +// @Tags authentication +// @Accept json +// @Produce json +// @Security securitydefinitions.basic +// @Success 204 "Session cleared" +// @Failure 500 {object} happydns.ErrorResponse +// @Router /auth/logout [post] func (lc *LoginController) Logout(c *gin.Context) { session := sessions.Default(c) diff --git a/internal/api/controller/domain.go b/internal/api/controller/domain.go index 3c7f8e63..53b5470b 100644 --- a/internal/api/controller/domain.go +++ b/internal/api/controller/domain.go @@ -243,7 +243,23 @@ func (dc *DomainController) RetrieveZone(c *gin.Context) { c.JSON(http.StatusOK, &zone.ZoneMeta) } -// ImportZone takes a bind style file +// ImportZone imports a zone from a BIND-style zone file. +// +// @Summary Import zone from file. +// @Schemes +// @Description Import a zone from a BIND-style zone file upload. +// @Tags zones +// @Accept multipart/form-data +// @Produce json +// @Security securitydefinitions.basic +// @Param domainId path string true "Domain identifier" +// @Param zone formData file true "Zone file to import" +// @Success 200 {object} happydns.Zone +// @Failure 400 {object} happydns.ErrorResponse "Invalid input or unable to read zone file" +// @Failure 401 {object} happydns.ErrorResponse "Authentication failure" +// @Failure 404 {object} happydns.ErrorResponse "Domain not found" +// @Failure 500 {object} happydns.ErrorResponse +// @Router /domains/{domainId}/zone [post] func (dc *DomainController) ImportZone(c *gin.Context) { user := middleware.MyUser(c) if user == nil { diff --git a/internal/api/controller/service_specs.go b/internal/api/controller/service_specs.go index 5ae4204d..c9c5fcc4 100644 --- a/internal/api/controller/service_specs.go +++ b/internal/api/controller/service_specs.go @@ -90,7 +90,7 @@ func (ssc *ServiceSpecsController) GetServiceSpecIcon(c *gin.Context) { // @Param serviceType path string true "The service's type" // @Success 200 {object} happydns.ServiceSpecs // @Failure 404 {object} happydns.ErrorResponse "Service type does not exist" -// @Router /services/_specs/{serviceType} [get] +// @Router /service_specs/{serviceType} [get] func (ssc *ServiceSpecsController) GetServiceSpec(c *gin.Context) { svctype := c.MustGet("servicetype").(reflect.Type) diff --git a/internal/api/controller/user.go b/internal/api/controller/user.go index e2a34b03..16c7448b 100644 --- a/internal/api/controller/user.go +++ b/internal/api/controller/user.go @@ -160,6 +160,21 @@ func (uc *UserController) ChangeUserSettings(c *gin.Context) { c.JSON(http.StatusOK, user.Settings) } +// deleteMyUser deletes the current user's account. +// +// @Summary Delete user account. +// @Schemes +// @Description Delete the current user's account and all associated data. +// @Tags users +// @Accept json +// @Produce json +// @Param userId path string true "User identifier" +// @Security securitydefinitions.basic +// @Success 204 "User deleted" +// @Failure 401 {object} happydns.ErrorResponse "Authentication failure" +// @Failure 403 {object} happydns.ErrorResponse "Not your account" +// @Failure 500 {object} happydns.ErrorResponse +// @Router /users/{userId} [delete] func (uc *UserController) DeleteMyUser(c *gin.Context) { user := c.MustGet("user").(*happydns.User) diff --git a/internal/api/controller/zone.go b/internal/api/controller/zone.go index 59005bb5..262e1e15 100644 --- a/internal/api/controller/zone.go +++ b/internal/api/controller/zone.go @@ -46,6 +46,21 @@ func NewZoneController(zoneService happydns.ZoneUsecase, domainService happydns. } } +// getZone retrieves a zone's information. +// +// @Summary Retrieve a zone. +// @Schemes +// @Description Retrieve information about a zone. +// @Tags zones +// @Accept json +// @Produce json +// @Security securitydefinitions.basic +// @Param domainId path string true "Domain identifier" +// @Param zoneId path string true "Zone identifier" +// @Success 200 {object} happydns.Zone +// @Failure 401 {object} happydns.ErrorResponse "Authentication failure" +// @Failure 404 {object} happydns.ErrorResponse "Domain or Zone not found" +// @Router /domains/{domainId}/zone/{zoneId} [get] func (zc *ZoneController) GetZone(c *gin.Context) { zone := c.MustGet("zone").(*happydns.Zone)