A better swagger for Iris

Read the _examples/basic for migration

.gitignore

@@ -1 +1,3 @@
 .vscode
+.sum
+*.exe

.travis.yml

@@ -2,15 +2,3 @@ language: go
 
 go:
   - 1.15.x
-
-matrix:
-  fast_finish: true
-  include:
-  - go: 1.15.x
-    env: GO111MODULE=on
-
-script:
-  - go test -coverprofile=coverage.txt -covermode=atomic
-
-after_success:
-  - bash <(curl -s https://codecov.io/bash)

README.md

@@ -3,14 +3,13 @@
 [Iris](https://github.com/kataras/iris) middleware to automatically generate RESTful API documentation with Swagger 2.0 as requested at [#1231](https://github.com/kataras/iris/issues/1231).
 
 [![Travis branch](https://img.shields.io/travis/iris-contrib/swagger/v12.svg)](https://travis-ci.org/iris-contrib/swagger)
-[![Codecov branch](https://img.shields.io/codecov/c/github/iris-contrib/swagger/master.svg)](https://codecov.io/gh/iris-contrib/swagger)
 [![Go Report Card](https://goreportcard.com/badge/github.com/iris-contrib/swagger)](https://goreportcard.com/report/github.com/iris-contrib/swagger)
-[![GoDoc](https://godoc.org/github.com/iris-contrib/swagger?status.svg)](https://godoc.org/github.com/iris-contrib/swagger)
-[![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Firis-contrib%2Fswagger.svg?type=shield)](https://app.fossa.io/projects/git%2Bgithub.com%2Firis-contrib%2Fswagger?ref=badge_shield)
+[![GoDoc](https://godoc.org/github.com/iris-contrib/swagger?status.svg)](https://pkg.go.dev/github.com/iris-contrib/swagger)
 
 ## Usage
 
 ### Start using it
+
 1. Add comments to your API source code, [See Declarative Comments Format](https://swaggo.github.io/swaggo.io/declarative_comments_format/).
 2. Download [Swag](https://github.com/swaggo/swag) for Go by using:
 
@@ -27,7 +26,7 @@ $ swag init
 4. Download [swagger for Iris](https://github.com/iris-contrib/swagger) by using:
 
 ```sh
-$ go get github.com/iris-contrib/swagger/v12@v12.2.0-alpha
+$ go get github.com/iris-contrib/swagger/v12@master
 ```
 
 And import following in your code:
@@ -38,7 +37,7 @@ import "github.com/iris-contrib/swagger/v12/swaggerFiles" // swagger embed files
 
 ```
 
-### Canonical example:
+### Example Code:
 
 ```go
 package main
@@ -49,7 +48,9 @@ import (
     "github.com/iris-contrib/swagger/v12"
     "github.com/iris-contrib/swagger/v12/swaggerFiles"
 
-    _ "./docs" // docs is generated by Swag CLI, you have to import it.
+    _ "github.com/your_username/your_project/docs"
+    // docs folder should be generated by Swag CLI (swag init),
+    // you have to import it.
 )
 
 // @title Swagger Example API
@@ -64,64 +65,37 @@ import (
 // @license.name Apache 2.0
 // @license.url http://www.apache.org/licenses/LICENSE-2.0.html
 
-// @host petstore.swagger.io
+// @host localhost:8080
 // @BasePath /v2
 func main() {
     app := iris.New()
 
-    config := &swagger.Config{
-        URL: "http://localhost:8080/swagger/doc.json", //The url pointing to API definition
+    config := swagger.Config{
+        // The url pointing to API definition.
+        URL:          "http://localhost:8080/swagger/doc.json",
+        DeepLinking:  true,
+        DocExpansion: "list",
+        DomID:        "#swagger-ui",
+        // The UI prefix URL (see route).
+        Prefix:       "/swagger",
     }
-    // use swagger middleware to 
-    app.Get("/swagger/{any:path}", swagger.CustomWrapHandler(config, swaggerFiles.Handler))
+    swaggerUI := swagger.Handler(swaggerFiles.Handler, config)
+
+    // Register on http://localhost:8080/swagger
+    app.Get("/swagger", swaggerUI)
+    // And the wildcard one for index.html, *.js, *.css and e.t.c.
+    app.Get("/swagger/{any:path}", swaggerUI)
 
-    app.Run(iris.Addr(":8080"))
+    app.Listen(":8080")
 }
 ```
 
-5. Run it, and browser to http://localhost:8080/swagger/index.html, you can see Swagger 2.0 Api documents.
+5. Run it, and browse to http://localhost:8080/swagger/index.html, you can see Swagger 2.0 API documentation.
 
 ![swagger_index.html](example.png)
 
-6. If you want to disable swagger when some environment variable is set, use `DisablingWrapHandler`
-
-### Example with disabling:
+6. If you want to disable swagger when some environment variable is set, use `DisablingHandler` instead of `Handler`.
 
 ```go
-package main
-
-import (
-    "github.com/kataras/iris/v12"
-
-    "github.com/iris-contrib/swagger/v12"
-    "github.com/iris-contrib/swagger/v12/swaggerFiles"
-
-    _ "./docs" // docs is generated by Swag CLI, you have to import it.
-)
-
-// @title Swagger Example API
-// @version 1.0
-// @description This is a sample server Petstore server.
-// @termsOfService http://swagger.io/terms/
-
-// @contact.name API Support
-// @contact.url http://www.swagger.io/support
-// @contact.email [email protected]
-
-// @license.name Apache 2.0
-// @license.url http://www.apache.org/licenses/LICENSE-2.0.html
-
-// @host petstore.swagger.io
-// @BasePath /v2
-func main() {
-    app := iris.New()
-
-    // use swagger middleware to 
-    app.Get("/swagger/{any:path}", swagger.DisablingWrapHandler(swaggerFiles.Handler, "NAME_OF_ENV_VARIABLE"))
-
-    app.Run(iris.Addr(":8080"))
-}
+swagger.DisablingHandler(swaggerFiles.Handler, config)
 ```
-
-Then, if you set envioment variable `NAME_OF_ENV_VARIABLE` to anything, `/swagger/*any`
-will respond 404, just like when route unspecified.

_examples/basic/README.md

@@ -0,0 +1,9 @@
+# Basic
+
+```sh
+$ go get github.com/swaggo/swag/cmd/swag
+$ swag init
+$ go run main.go
+```
+
+Navigate to <http://localhost:8080/swagger>.

example/basic/api/api.go → _examples/basic/api/api.go

@@ -1,9 +1,6 @@
 package api
 
 import (
-	"fmt"
-
-	"github.com/iris-contrib/swagger/v12/example/basic/web"
 	"github.com/kataras/iris/v12"
 )
 
@@ -18,8 +15,13 @@ import (
 // @Failure 404 {object} web.APIError "Can not find ID"
 // @Router /testapi/get-string-by-int/{some_id} [get]
 func GetStringByInt(ctx iris.Context) {
-	err := web.APIError{}
-	fmt.Println(err)
+	// err := web.APIError{}
+	// fmt.Println(err)
+
+	id := ctx.Params().GetIntDefault("some_id", 0)
+	ctx.JSON(Pet3{
+		ID: id,
+	})
 }
 
 // @Description get struct array by ID
@@ -32,7 +34,10 @@ func GetStringByInt(ctx iris.Context) {
 // @Failure 400 {object} web.APIError "We need ID!!"
 // @Failure 404 {object} web.APIError "Can not find ID"
 // @Router /testapi/get-struct-array-by-string/{some_id} [get]
-func GetStructArrayByString(ctx iris.Context) {}
+func GetStructArrayByString(ctx iris.Context) {
+	id := ctx.Params().GetIntDefault("some_id", 0)
+	ctx.Writef("OK: GetStructArrayByString:  %d", id)
+}
 
 type Pet3 struct {
 	ID int `json:"id"`

example/basic/docs/docs.go → _examples/basic/docs/docs.go

@@ -1,21 +1,23 @@
 // GENERATED BY THE COMMAND ABOVE; DO NOT EDIT
-// This file was generated by swaggo/swag at
-// 2019-04-14 04:38:21.2050816 +0300 EEST m=+0.023094301
+// This file was generated by swaggo/swag
 
 package docs
 
 import (
 	"bytes"
+	"encoding/json"
+	"strings"
 
 	"github.com/alecthomas/template"
 	"github.com/swaggo/swag"
 )
 
 var doc = `{
+    "schemes": {{ marshal .Schemes }},
     "swagger": "2.0",
     "info": {
-        "description": "This is a sample server Petstore server.",
-        "title": "Swagger Example API",
+        "description": "{{.Description}}",
+        "title": "{{.Title}}",
         "termsOfService": "http://swagger.io/terms/",
         "contact": {
             "name": "API Support",
@@ -26,10 +28,10 @@ var doc = `{
             "name": "Apache 2.0",
             "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
         },
-        "version": "1.0"
+        "version": "{{.Version}}"
     },
-    "host": "petstore.swagger.io",
-    "basePath": "/v2",
+    "host": "{{.Host}}",
+    "basePath": "{{.BasePath}}",
     "paths": {
         "/testapi/get-string-by-int/{some_id}": {
             "get": {
@@ -60,14 +62,12 @@ var doc = `{
                     "400": {
                         "description": "We need ID!!",
                         "schema": {
-                            "type": "object",
                             "$ref": "#/definitions/web.APIError"
                         }
                     },
                     "404": {
                         "description": "Can not find ID",
                         "schema": {
-                            "type": "object",
                             "$ref": "#/definitions/web.APIError"
                         }
                     }
@@ -116,14 +116,12 @@ var doc = `{
                     "400": {
                         "description": "We need ID!!",
                         "schema": {
-                            "type": "object",
                             "$ref": "#/definitions/web.APIError"
                         }
                     },
                     "404": {
                         "description": "Can not find ID",
                         "schema": {
-                            "type": "object",
                             "$ref": "#/definitions/web.APIError"
                         }
                     }
@@ -150,23 +148,39 @@ type swaggerInfo struct {
 	Version     string
 	Host        string
 	BasePath    string
+	Schemes     []string
 	Title       string
 	Description string
 }
 
 // SwaggerInfo holds exported Swagger Info so clients can modify it
-var SwaggerInfo swaggerInfo
+var SwaggerInfo = swaggerInfo{
+	Version:     "1.0",
+	Host:        "localhost:8080",
+	BasePath:    "/v2",
+	Schemes:     []string{},
+	Title:       "Swagger Example API",
+	Description: "This is a sample server Petstore server.",
+}
 
 type s struct{}
 
 func (s *s) ReadDoc() string {
-	t, err := template.New("swagger_info").Parse(doc)
+	sInfo := SwaggerInfo
+	sInfo.Description = strings.Replace(sInfo.Description, "\n", "\\n", -1)
+
+	t, err := template.New("swagger_info").Funcs(template.FuncMap{
+		"marshal": func(v interface{}) string {
+			a, _ := json.Marshal(v)
+			return string(a)
+		},
+	}).Parse(doc)
 	if err != nil {
 		return doc
 	}
 
 	var tpl bytes.Buffer
-	if err := t.Execute(&tpl, SwaggerInfo); err != nil {
+	if err := t.Execute(&tpl, sInfo); err != nil {
 		return doc
 	}
 

example/basic/docs/swagger.json → _examples/basic/docs/swagger.json

@@ -15,7 +15,7 @@
         },
         "version": "1.0"
     },
-    "host": "petstore.swagger.io",
+    "host": "localhost:8080",
     "basePath": "/v2",
     "paths": {
         "/testapi/get-string-by-int/{some_id}": {
@@ -47,14 +47,12 @@
                     "400": {
                         "description": "We need ID!!",
                         "schema": {
-                            "type": "object",
                             "$ref": "#/definitions/web.APIError"
                         }
                     },
                     "404": {
                         "description": "Can not find ID",
                         "schema": {
-                            "type": "object",
                             "$ref": "#/definitions/web.APIError"
                         }
                     }
@@ -103,14 +101,12 @@
                     "400": {
                         "description": "We need ID!!",
                         "schema": {
-                            "type": "object",
                             "$ref": "#/definitions/web.APIError"
                         }
                     },
                     "404": {
                         "description": "Can not find ID",
                         "schema": {
-                            "type": "object",
                             "$ref": "#/definitions/web.APIError"
                         }
                     }

example/basic/docs/swagger.yaml → _examples/basic/docs/swagger.yaml

@@ -7,7 +7,7 @@ definitions:
       errorMessage:
         type: string
     type: object
-host: petstore.swagger.io
+host: localhost:8080
 info:
   contact:
     email: [email protected]
@@ -43,12 +43,10 @@ paths:
           description: We need ID!!
           schema:
             $ref: '#/definitions/web.APIError'
-            type: object
         "404":
           description: Can not find ID
           schema:
             $ref: '#/definitions/web.APIError'
-            type: object
       summary: Add a new pet to the store
   /testapi/get-struct-array-by-string/{some_id}:
     get:
@@ -82,10 +80,8 @@ paths:
           description: We need ID!!
           schema:
             $ref: '#/definitions/web.APIError'
-            type: object
         "404":
           description: Can not find ID
           schema:
             $ref: '#/definitions/web.APIError'
-            type: object
 swagger: "2.0"