Update swagger documentation

jmbessa · Apr 4, 2024 · 4c5f3a8 · 4c5f3a8
1 parent 728fd19
commit 4c5f3a8
Show file tree

Hide file tree

Showing 8 changed files with 401 additions and 40 deletions.
diff --git a/docs/docs.go b/docs/docs.go
diff --git a/docs/swagger.json b/docs/swagger.json
diff --git a/docs/swagger.yaml b/docs/swagger.yaml
@@ -1,5 +1,11 @@
-basePath: /v1
 definitions:
+  models.Password:
+    properties:
+      current:
+        type: string
+      new:
+        type: string
+    type: object
   models.Post:
     properties:
       authorId:
@@ -32,6 +38,13 @@ definitions:
       password:
         type: string
     type: object
+  models.UserRequest:
+    properties:
+      email:
+        type: string
+      password:
+        type: string
+    type: object
 info:
   contact: {}
   description: RESTful API developed in Golang, intended to serve as the backend for
@@ -49,7 +62,7 @@ paths:
         name: credentials
         required: true
         schema:
-          $ref: '#/definitions/models.User'
+          $ref: '#/definitions/models.UserRequest'
       produces:
       - text/plain
       responses:
@@ -69,6 +82,7 @@ paths:
           description: Internal Server Error
           schema:
             type: object
+      summary: Authenticate user
       tags:
       - authentication
   /posts:
@@ -87,6 +101,9 @@ paths:
           description: Internal Server Error
           schema:
             type: object
+      security:
+      - Bearer: []
+      summary: Get all posts
       tags:
       - posts
     post:
@@ -95,11 +112,12 @@ paths:
       description: Create a new post with the data sent in the request body
       parameters:
       - description: Create Post
+        example: '{"title": "string", "content": "string"}'
         in: body
         name: post
         required: true
         schema:
-          $ref: '#/definitions/models.Post'
+          type: string
       produces:
       - application/json
       responses:
@@ -124,7 +142,9 @@ paths:
           schema:
             type: object
       security:
+      - Bearer: []
       - ApiKeyAuth: []
+      summary: Create a new post
       tags:
       - posts
   /posts/{postId}:
@@ -154,7 +174,9 @@ paths:
           schema:
             type: object
       security:
+      - Bearer: []
       - ApiKeyAuth: []
+      summary: Delete a post
       tags:
       - posts
     get:
@@ -180,6 +202,9 @@ paths:
           description: Internal Server Error
           schema:
             type: object
+      security:
+      - Bearer: []
+      summary: Get a post by ID
       tags:
       - posts
     put:
@@ -193,11 +218,12 @@ paths:
         required: true
         type: integer
       - description: Post data
+        example: '{"title": "string", "content": "string"}'
         in: body
         name: post
         required: true
         schema:
-          $ref: '#/definitions/models.Post'
+          type: string
       produces:
       - application/json
       responses:
@@ -222,7 +248,9 @@ paths:
           schema:
             type: object
       security:
+      - Bearer: []
       - ApiKeyAuth: []
+      summary: Update a post
       tags:
       - posts
   /posts/{postId}/dislike:
@@ -248,7 +276,9 @@ paths:
           schema:
             type: object
       security:
+      - Bearer: []
       - ApiKeyAuth: []
+      summary: Dislike a post
       tags:
       - posts
   /posts/{postId}/like:
@@ -274,19 +304,16 @@ paths:
           schema:
             type: object
       security:
+      - Bearer: []
       - ApiKeyAuth: []
+      summary: Like a post
       tags:
       - posts
   /users:
     get:
       consumes:
       - application/json
       description: Retrieve all users, optionally filtered by name or nickname
-      parameters:
-      - description: Name or nickname of the user to filter
-        in: query
-        name: user
-        type: string
       produces:
       - application/json
       responses:
@@ -300,6 +327,9 @@ paths:
           description: Internal Server Error
           schema:
             type: object
+      security:
+      - Bearer: []
+      summary: Get all users
       tags:
       - users
     post:
@@ -328,6 +358,9 @@ paths:
           description: Internal Server Error
           schema:
             type: object
+      security:
+      - Bearer: []
+      summary: Create a new user
       tags:
       - users
   /users/{userID}:
@@ -360,6 +393,9 @@ paths:
           description: Internal Server Error
           schema:
             type: object
+      security:
+      - Bearer: []
+      summary: Delete user by ID
       tags:
       - users
     get:
@@ -387,6 +423,9 @@ paths:
           description: Internal Server Error
           schema:
             type: object
+      security:
+      - Bearer: []
+      summary: Get user by ID
       tags:
       - users
     put:
@@ -418,6 +457,9 @@ paths:
           description: Internal Server Error
           schema:
             type: object
+      security:
+      - Bearer: []
+      summary: Update user by ID
       tags:
       - users
   /users/{userID}/follow:
@@ -446,6 +488,9 @@ paths:
           description: Internal Server Error
           schema:
             type: object
+      security:
+      - Bearer: []
+      summary: Follow user by ID
       tags:
       - users
   /users/{userID}/followers:
@@ -476,6 +521,9 @@ paths:
           description: Internal Server Error
           schema:
             type: object
+      security:
+      - Bearer: []
+      summary: Search followers of user
       tags:
       - users
   /users/{userID}/following:
@@ -506,6 +554,9 @@ paths:
           description: Internal Server Error
           schema:
             type: object
+      security:
+      - Bearer: []
+      summary: Search following users of user
       tags:
       - users
   /users/{userID}/unfollow:
@@ -534,6 +585,9 @@ paths:
           description: Internal Server Error
           schema:
             type: object
+      security:
+      - Bearer: []
+      summary: Unfollow user by ID
       tags:
       - users
   /users/{userID}/update-password:
@@ -547,6 +601,12 @@ paths:
         name: userID
         required: true
         type: integer
+      - description: New password
+        in: body
+        name: password
+        required: true
+        schema:
+          $ref: '#/definitions/models.Password'
       produces:
       - application/json
       responses:
@@ -566,6 +626,9 @@ paths:
           description: Internal Server Error
           schema:
             type: object
+      security:
+      - Bearer: []
+      summary: Update user password
       tags:
       - users
   /users/{userId}/posts:
@@ -594,6 +657,15 @@ paths:
           description: Internal Server Error
           schema:
             type: object
+      security:
+      - Bearer: []
+      summary: Get all posts by user
       tags:
       - posts
+securityDefinitions:
+  Bearer:
+    description: Provide the JWT token with prefix 'Bearer ' in the text box.
+    in: header
+    name: Authorization
+    type: apiKey
 swagger: "2.0"
diff --git a/main.go b/main.go
@@ -14,7 +14,10 @@ import (
 
 // @title SocialMedia-API
 // @description RESTful API developed in Golang, intended to serve as the backend for a social networking application
-// @BasePath /v1
+// @securityDefinitions.apikey Bearer
+// @in header
+// @name Authorization
+// @description Provide the JWT token with prefix 'Bearer ' in the text box.
 func main() {
 	config.Load()
 	r := router.Generate()

diff --git a/src/controllers/login.go b/src/controllers/login.go
@@ -18,7 +18,7 @@ import (
 // @Tags authentication
 // @Accept json
 // @Produce plain
-// @Param credentials body models.User true "User credentials"
+// @Param credentials body models.UserRequest true "User credentials"
 // @Success 200 {string} string "Authentication token"
 // @Failure 400 {object} object "Bad Request"
 // @Failure 401 {object} object "Unauthorized"
@@ -31,7 +31,7 @@ func Login(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	var user models.User
+	var user models.UserRequest
 
 	if err = json.Unmarshal(requestBody, &user); err != nil {
 		responses.Error(w, http.StatusBadRequest, err)
@@ -64,7 +64,7 @@ func Login(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	formattedToken := fmt.Sprintf("Token: %s", token)
+	formattedToken := fmt.Sprintf("Bearer %s", token)
 	w.Write([]byte(formattedToken))
 
 }
diff --git a/src/controllers/posts.go b/src/controllers/posts.go
@@ -20,7 +20,8 @@ import (
 // @Tags posts
 // @Accept  json
 // @Produce  json
-// @Param        post  body      models.Post  true  "Create Post"
+// @Security Bearer
+// @Param post body string true "Create Post" example({"title": "string", "content": "string"})
 // @Success      201  {object}  models.Post
 // @Failure      400  {object}  object       "Bad Request"
 // @Failure      401  {object}  object       "Unauthorized"
@@ -75,6 +76,7 @@ func CreatePost(w http.ResponseWriter, r *http.Request) {
 // @Description Retrieve all posts from the database
 // @Tags posts
 // @Produce json
+// @Security Bearer
 // @Success 200 {array} models.Post
 // @Failure 500 {object} object "Internal Server Error"
 // @Router /posts [get]
@@ -106,6 +108,7 @@ func GetPosts(w http.ResponseWriter, r *http.Request) {
 // @Description Retrieve a post by its ID from the database
 // @Tags posts
 // @Produce json
+// @Security Bearer
 // @Param postId path int true "Post ID"
 // @Success 200 {object} models.Post
 // @Failure 400 {object} object "Bad Request"
@@ -141,8 +144,9 @@ func GetPost(w http.ResponseWriter, r *http.Request) {
 // @Tags posts
 // @Accept json
 // @Produce json
+// @Security Bearer
 // @Param postId path int true "Post ID"
-// @Param post body models.Post true "Post data"
+// @Param post body string true "Post data" example({"title": "string", "content": "string"})
 // @Success 204 {object} object
 // @Failure 400 {object} object "Bad Request"
 // @Failure 401 {object} object "Unauthorized"
@@ -211,6 +215,7 @@ func UpdatePost(w http.ResponseWriter, r *http.Request) {
 // @Summary Delete a post
 // @Description Delete a post by its ID
 // @Tags posts
+// @Security Bearer
 // @Param postId path int true "Post ID"
 // @Success 204 {object} object
 // @Failure 400 {object} object "Bad Request"
@@ -263,6 +268,7 @@ func DeletePost(w http.ResponseWriter, r *http.Request) {
 // @Description Retrieve all posts created by a specific user
 // @Tags posts
 // @Produce json
+// @Security Bearer
 // @Param userId path int true "User ID"
 // @Success 200 {array} models.Post
 // @Failure 400 {object} object "Bad Request"
@@ -296,6 +302,7 @@ func GetPostsPerUser(w http.ResponseWriter, r *http.Request) {
 // @Summary Like a post
 // @Description Increment the likes count for a post
 // @Tags posts
+// @Security Bearer
 // @Param postId path int true "Post ID"
 // @Success 204 {object} object
 // @Failure 400 {object} object "Bad Request"
@@ -330,6 +337,7 @@ func LikePost(w http.ResponseWriter, r *http.Request) {
 // @Summary Dislike a post
 // @Description Decrement the likes count for a post
 // @Tags posts
+// @Security Bearer
 // @Param postId path int true "Post ID"
 // @Success 204 {object} object
 // @Failure 400 {object} object "Bad Request"