golang-saas-starter-kit/example-project/internal/mid/saas-swagger/README.md

# 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}"`
    ```