chore: add multiple api example (#207)

* chore: add multiple api example
* chore: update README.md

README.md

@@ -143,6 +143,9 @@ Demo project tree, `swag init` is run at relative `.`
 └── main.go
 ```
 
+## Multiple APIs
+This feature where introduced in swag v1.7.9
+
 ## Configuration
 
 You can configure Swagger using different configuration options

example/multiple/README.md

@@ -0,0 +1,23 @@
+
+# Multiple API feature
+Since swag 1.7.9 we are allowing registration of multiple endpoints into the same server.
+
+Generate documentation for v1 endpoints
+```shell
+swag i -g main.go -dir api/v1 --instanceName v1
+```
+
+
+Generate documentation for v2 endpoints
+```shell
+swag i -g main.go -dir api/v2 --instanceName v2
+```
+
+Run example
+```shell
+    go run main.go
+```
+
+Now you can access the v1 swagger here [http://localhost:8080/swagger/v1/index.html](http://localhost:8080/swagger/v1/index.html) , 
+and v2 swagger here [http://localhost:8080/swagger/v2/index.html](http://localhost:8080/swagger/v2/index.html)
+

example/multiple/api/v1/example.go

@@ -0,0 +1,26 @@
+package v1
+
+import (
+	"github.com/gin-gonic/gin"
+)
+
+type Book struct {
+	ID     int     `json:"id,omitempty"`
+	Title  string  `json:"title"`
+	Author string  `json:"author"`
+	Year   *uint16 `json:"year"`
+}
+
+//
+// @Summary Get a list of books in the the store
+// @Description get string by ID
+// @Accept  json
+// @Produce  json
+// @Success 200 {array} Book "ok"
+// @Router /books [get]
+func GetBooks(ctx *gin.Context) {
+	ctx.JSON(200, []Book{
+		{ID: 1, Title: "Book 1", Author: "Author 1", Year: nil},
+		{ID: 2, Title: "Book 2", Author: "Author 2", Year: nil},
+	})
+}

example/multiple/api/v1/main.go

@@ -0,0 +1,25 @@
+package v1
+
+import (
+	"github.com/gin-gonic/gin"
+)
+
+// @title Swagger Example API
+// @version 1.0
+// @description This is a sample 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
+
+// @BasePath /v1
+
+func Register(router *gin.Engine) {
+	v1 := router.Group("v1")
+
+	v1.GET("/books", GetBooks)
+}

example/multiple/api/v2/example.go

@@ -0,0 +1,26 @@
+package v2
+
+import (
+	"github.com/gin-gonic/gin"
+)
+
+type Book struct {
+	ID     int     `json:"id,omitempty"`
+	Title  string  `json:"title"`
+	Author string  `json:"author"`
+	Year   *uint16 `json:"year"`
+}
+
+//
+// @Summary Get a list of books in the the store
+// @Description get string by ID
+// @Accept  json
+// @Produce  json
+// @Success 200 {array} Book "ok"
+// @Router /books [get]
+func GetBooks(ctx *gin.Context) {
+	ctx.JSON(200, []Book{
+		{ID: 1, Title: "Book 3", Author: "Author 3", Year: nil},
+		{ID: 2, Title: "Book 4", Author: "Author 4", Year: nil},
+	})
+}

example/multiple/api/v2/main.go

@@ -0,0 +1,25 @@
+package v2
+
+import (
+	"github.com/gin-gonic/gin"
+)
+
+// @title Swagger Example API
+// @version 2.0
+// @description This is a sample 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
+
+// @BasePath /v2
+
+func Register(router *gin.Engine) {
+	v2 := router.Group("v2")
+
+	v2.GET("/books", GetBooks)
+}

example/multiple/docs/v1_docs.go

@@ -0,0 +1,87 @@
+// Package docs GENERATED BY SWAG; DO NOT EDIT
+// This file was generated by swaggo/swag
+package docs
+
+import "github.com/swaggo/swag"
+
+const docTemplatev1 = `{
+    "schemes": {{ marshal .Schemes }},
+    "swagger": "2.0",
+    "info": {
+        "description": "{{escape .Description}}",
+        "title": "{{.Title}}",
+        "termsOfService": "http://swagger.io/terms/",
+        "contact": {
+            "name": "API Support",
+            "url": "http://www.swagger.io/support",
+            "email": "[email protected]"
+        },
+        "license": {
+            "name": "Apache 2.0",
+            "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
+        },
+        "version": "{{.Version}}"
+    },
+    "host": "{{.Host}}",
+    "basePath": "{{.BasePath}}",
+    "paths": {
+        "/books": {
+            "get": {
+                "description": "get string by ID",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "summary": "Get a list of books in the the store",
+                "responses": {
+                    "200": {
+                        "description": "ok",
+                        "schema": {
+                            "type": "array",
+                            "items": {
+                                "$ref": "#/definitions/v1.Book"
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    },
+    "definitions": {
+        "v1.Book": {
+            "type": "object",
+            "properties": {
+                "author": {
+                    "type": "string"
+                },
+                "id": {
+                    "type": "integer"
+                },
+                "title": {
+                    "type": "string"
+                },
+                "year": {
+                    "type": "integer"
+                }
+            }
+        }
+    }
+}`
+
+// SwaggerInfov1 holds exported Swagger Info so clients can modify it
+var SwaggerInfov1 = &swag.Spec{
+	Version:          "1.0",
+	Host:             "",
+	BasePath:         "/v1",
+	Schemes:          []string{},
+	Title:            "Swagger Example API",
+	Description:      "This is a sample server.",
+	InfoInstanceName: "v1",
+	SwaggerTemplate:  docTemplatev1,
+}
+
+func init() {
+	swag.Register(SwaggerInfov1.InstanceName(), SwaggerInfov1)
+}

example/multiple/docs/v1_swagger.json

@@ -0,0 +1,63 @@
+{
+    "swagger": "2.0",
+    "info": {
+        "description": "This is a sample server.",
+        "title": "Swagger Example API",
+        "termsOfService": "http://swagger.io/terms/",
+        "contact": {
+            "name": "API Support",
+            "url": "http://www.swagger.io/support",
+            "email": "[email protected]"
+        },
+        "license": {
+            "name": "Apache 2.0",
+            "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
+        },
+        "version": "1.0"
+    },
+    "basePath": "/v1",
+    "paths": {
+        "/books": {
+            "get": {
+                "description": "get string by ID",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "summary": "Get a list of books in the the store",
+                "responses": {
+                    "200": {
+                        "description": "ok",
+                        "schema": {
+                            "type": "array",
+                            "items": {
+                                "$ref": "#/definitions/v1.Book"
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    },
+    "definitions": {
+        "v1.Book": {
+            "type": "object",
+            "properties": {
+                "author": {
+                    "type": "string"
+                },
+                "id": {
+                    "type": "integer"
+                },
+                "title": {
+                    "type": "string"
+                },
+                "year": {
+                    "type": "integer"
+                }
+            }
+        }
+    }
+}

example/multiple/docs/v1_swagger.yaml

@@ -0,0 +1,42 @@
+basePath: /v1
+definitions:
+  v1.Book:
+    properties:
+      author:
+        type: string
+      id:
+        type: integer
+      title:
+        type: string
+      year:
+        type: integer
+    type: object
+info:
+  contact:
+    email: [email protected]
+    name: API Support
+    url: http://www.swagger.io/support
+  description: This is a sample server.
+  license:
+    name: Apache 2.0
+    url: http://www.apache.org/licenses/LICENSE-2.0.html
+  termsOfService: http://swagger.io/terms/
+  title: Swagger Example API
+  version: "1.0"
+paths:
+  /books:
+    get:
+      consumes:
+      - application/json
+      description: get string by ID
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: ok
+          schema:
+            items:
+              $ref: '#/definitions/v1.Book'
+            type: array
+      summary: Get a list of books in the the store
+swagger: "2.0"