From b2251084d4bee8209662a41cdec7b3b7e77f891a Mon Sep 17 00:00:00 2001
From: ispiroglu <evrenn.ispiroglu@gmail.com>
Date: Sun, 25 Aug 2024 00:32:27 +0300
Subject: [PATCH] docs(swagger): add swagger documentation

---
 docs/modules/swagger.md                       | 124 ++++++++++++++++++
 example/server/request.go                     |   5 +-
 .../server/resources/configs/application.yml  |   7 +
 3 files changed, 134 insertions(+), 2 deletions(-)
 create mode 100644 docs/modules/swagger.md

diff --git a/docs/modules/swagger.md b/docs/modules/swagger.md
new file mode 100644
index 0000000..ae6bf12
--- /dev/null
+++ b/docs/modules/swagger.md
@@ -0,0 +1,124 @@
+# Swagger Module
+
+Swagger module is for generating swagger endpoints for route definitions. 
+
+The Swagger module automatically generates Swagger endpoints for your route definitions, providing an interactive API documentation interface. This module relies on the `EndpointDefinition` conversion of the route definitions created by the Server module. Therefore, the Server module is required for the Swagger module to function.
+The swagger documents are embedded in the application itself, there is no redirecting.
+
+### Usage
+To include the Swagger module in your Chaki application, add it to the `app.Use` function alongside the Server module:
+```go
+...
+
+app := chaki.New()
+
+app.Use(
+    server.Module(),
+    swagger.Module(),
+)
+
+....
+```
+
+### How it works?
+The Server module generates and stores route definitions, each containing a Meta model, which includes metadata about the route.
+```go
+type Meta struct {
+	Method        string
+	Path          string
+	Name          string
+	Desc          string
+	Func          fiber.Handler
+	Req           reflect.Type
+	Res           reflect.Type
+	Middlewares   []fiber.Handler
+	DefaultStatus int
+}
+```
+
+The Swagger module converts this metadata into Swagger definitions and paths based on the request model. If a request model includes a JSON body parameter, the Swagger module creates a corresponding definition and adds a reference to it in the endpoint's parameters field. For query and path variables, it automatically includes them in the parameters field.
+
+
+For example, given the following request model:
+```go
+type GreetWithBodyRequest struct {
+    Text           string `json:"text" validate:""`
+    RepeatTimes    int    `json:"repeatTimes" validate:"required"`
+    NecessaryParam string `query:"necessaryParam" validate:"required"`
+}
+```
+
+The Swagger module generates the following JSON:
+```json lines
+{
+  "definitions": {
+    "GreetWithBodyRequest": {
+      "properties": {
+        "repeatTimes": {
+          "format": "int",
+          "type": "integer"
+        },
+        "text": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "repeatTimes"
+      ],
+      "type": "object"
+    }
+  },
+  
+  /// ...
+
+  "paths": {
+    "/hello/body": {
+      "post": {
+        /// ...
+        "parameters": [
+          {
+            "description": "",
+            "in": "query",
+            "name": "necessaryParam",
+            "required": true,
+            "type": "string"
+          },
+          {
+            "description": "",
+            "in": "body",
+            "name": "body",
+            "required": true,
+            "schema": {
+              "$ref": "#/definitions/GreetWithBodyRequest"
+            }
+          }
+        ],
+        /// ...
+    },}
+    /// ...
+  }
+}
+
+```
+
+### Config
+The Swagger module offers simple configurations to customize the generated API documentation. Below are the default values:
+
+```yaml
+
+info:
+  description: ""
+  version: 1.0.0
+  title: Application
+  terms: http://swagger.io/terms/
+  email: ""
+```
+- Description: A brief description of your API. This field is optional.
+- Version: The version of your API. Defaults to 1.0.0.
+- Title: The title of your API documentation. Defaults to Application.
+- Terms: A URL to the terms of service for your API. Defaults to http://swagger.io/terms/.
+- Email: The contact email for API support or inquiries.
+
+
+
+
diff --git a/example/server/request.go b/example/server/request.go
index e3b5e30..5f86c8e 100644
--- a/example/server/request.go
+++ b/example/server/request.go
@@ -1,8 +1,9 @@
 package main
 
 type GreetWithBodyRequest struct {
-	Text        string `json:"text" validate:"required,min=3,max=100,textValidator"`
-	RepeatTimes int    `json:"repeatTimes" validate:"required,gte=1,lte=5"`
+	Text           string `json:"text" validate:""`
+	RepeatTimes    int    `json:"repeatTimes" validate:"required"`
+	NecessaryParam string `query:"necessaryParam" validate:"required"`
 }
 
 type GreetWithQueryRequest struct {
diff --git a/example/server/resources/configs/application.yml b/example/server/resources/configs/application.yml
index c8075a4..91cf8e3 100644
--- a/example/server/resources/configs/application.yml
+++ b/example/server/resources/configs/application.yml
@@ -3,3 +3,10 @@ server:
     # to be able to use wildcard, we need to declare it between double quotes.
     allowedOrigins: "*"
     allowCredentials: false
+
+info:
+  description: "this app is an example usage of Chaki."
+  version: 1.0.3
+  title: Example Application
+  terms: http://swagger.io/terms/
+  email: "example@mail.com"
\ No newline at end of file