moved example-project files back a directory

2025-08-08 22:36:41 +02:00 · 2019-07-13 11:42:37 -08:00
parent 541a279b6f
commit bcf022aa18
144 changed files with 200 additions and 206 deletions
--- a/internal/mid/saas-swagger/README.md
+++ b/internal/mid/saas-swagger/README.md
@ -0,0 +1,121 @@
+# SaaS swagger
+
+Copyright 2019, Geeks Accelerator  
+accelerator@geeksinthewoods.com.com
+
+
+## Description
+
+saas middleware to automatically generate RESTful API documentation with Swagger 2.0.
+
+
+## Usage
+
+### Start using it
+1. Add comments to your API source code, [See Declarative Comments Format](https://github.com/swaggo/swag#declarative-comments-format).
+
+2. Download [Swag](https://github.com/swaggo/swag) for Go by using:
+    ```sh
+    $ go get github.com/swaggo/swag/cmd/swag
+    ```
+
+3. Run the [Swag](https://github.com/swaggo/swag) in your Go project root folder which contains `main.go` file, [Swag](https://github.com/swaggo/swag) will parse comments and generate required files(`docs` folder and `docs/doc.go`).
+    ```sh_ "github.com/swaggo/echo-swagger/v2/example/docs"
+    $ swag init
+    ```
+
+4. Import following in your code:
+    ```go
+    import "geeks-accelerator/oss/saas-starter-kit/example-project/internal/mid/saas-swagger" // saas-swagger middleware
+    ```
+
+    **Canonical example:**
+    
+    ```go
+    package main
+    
+    import (
+        "context"
+        "log"
+        "net/http"
+        "os"
+        "os/signal"
+        "syscall"
+        "time"
+    
+        "geeks-accelerator/oss/saas-starter-kit/example-project/internal/mid"
+        saasSwagger "geeks-accelerator/oss/saas-starter-kit/example-project/internal/mid/saas-swagger"
+        _ "geeks-accelerator/oss/saas-starter-kit/example-project/internal/mid/saas-swagger/example/docs" // docs is generated by Swag CLI, you have to import it.
+        "geeks-accelerator/oss/saas-starter-kit/example-project/internal/platform/web"
+    )
+    
+    // @title SaaS Example API
+    // @version 1.0
+    // @description This is a sample server celler server.
+    // @termsOfService http://geeksinthewoods.com/terms
+    
+    // @contact.name API Support
+    // @contact.email support@geeksinthewoods.com
+    // @contact.url https://gitlab.com/geeks-accelerator/oss/saas-starter-kit
+    
+    // @license.name Apache 2.0
+    // @license.url http://www.apache.org/licenses/LICENSE-2.0.html
+    
+    // @host example-api.saas.geeksinthewoods.com
+    // @BasePath /v1
+    
+    func main() {
+    
+        // Logging
+        log := log.New(os.Stdout, "", log.LstdFlags|log.Lmicroseconds|log.Lshortfile)
+    
+        // Configuration
+        ... 
+    
+        // =========================================================================
+        // Start API Service
+        
+        // Make a channel to listen for an interrupt or terminate signal from the OS.
+        // Use a buffered channel because the signal package requires it.
+        shutdown := make(chan os.Signal, 1)
+        signal.Notify(shutdown, os.Interrupt, syscall.SIGTERM)
+    
+        // Construct the web.App which holds all routes as well as common Middleware.
+        app := web.NewApp(shutdown, log, mid.Trace(), mid.Logger(log), mid.Errors(log), mid.Metrics(), mid.Panics())
+    
+        app.Handle("GET", "/swagger/", saasSwagger.WrapHandler)
+        app.Handle("GET", "/swagger/*", saasSwagger.WrapHandler)
+    
+        /*
+            Or can use SaasWrapHandler func with configurations.
+            url := saasSwagger.URL("http://localhost:1323/swagger/doc.json") //The url pointing to API definition
+            e.GET("/swagger/*", saasSwagger.SaasWrapHandler(url))
+        */
+    
+        ... 
+    }
+    ```
+
+5. Run it, and browser to http://localhost:1323/swagger/index.html, you can see Swagger 2.0 Api documents.
+
+
+### Dynamic Placeholders
+
+To help ease use of the Swagger UI, dynamic placeholders have been added to the middleware. They are replaced on each 
+request before the JSON is returned to the browser. These can be used in an `example` struct tag.   
+
+1. `{RANDOM_UUID}`
+    Generates a random UUID.
+
+    Example:
+    ```
+    Name string `json:"name" validate:"required" example:"Company {RANDOM_UUID}"`
+    ```
+
+2. `{RANDOM_EMAIL}`
+    Generate a random email address. Format will be UUID@example.com
+    
+    Example:
+    ```
+    Email string  `json:"email" validate:"required,email" example:"{RANDOM_EMAIL}"`
+    ```