Add missing API documentation

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)
 

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 {

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)
 

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)
 

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)