chore: add multiple api example (#207)
* chore: add multiple api example * chore: update README.md
This commit is contained in:
Bogdan U
@@ -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)
|
||||
|
||||
@@ -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},
|
||||
})
|
||||
}
|
||||
@@ -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 support@swagger.io
|
||||
|
||||
// @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)
|
||||
}
|
||||
@@ -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},
|
||||
})
|
||||
}
|
||||
@@ -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 support@swagger.io
|
||||
|
||||
// @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)
|
||||
}
|
||||
@@ -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": "support@swagger.io"
|
||||
},
|
||||
"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)
|
||||
}
|
||||
@@ -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": "support@swagger.io"
|
||||
},
|
||||
"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"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -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: support@swagger.io
|
||||
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"
|
||||
@@ -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 docTemplatev2 = `{
|
||||
"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": "support@swagger.io"
|
||||
},
|
||||
"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/v2.Book"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"definitions": {
|
||||
"v2.Book": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"author": {
|
||||
"type": "string"
|
||||
},
|
||||
"id": {
|
||||
"type": "integer"
|
||||
},
|
||||
"title": {
|
||||
"type": "string"
|
||||
},
|
||||
"year": {
|
||||
"type": "integer"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}`
|
||||
|
||||
// SwaggerInfov2 holds exported Swagger Info so clients can modify it
|
||||
var SwaggerInfov2 = &swag.Spec{
|
||||
Version: "2.0",
|
||||
Host: "",
|
||||
BasePath: "/v2",
|
||||
Schemes: []string{},
|
||||
Title: "Swagger Example API",
|
||||
Description: "This is a sample server.",
|
||||
InfoInstanceName: "v2",
|
||||
SwaggerTemplate: docTemplatev2,
|
||||
}
|
||||
|
||||
func init() {
|
||||
swag.Register(SwaggerInfov2.InstanceName(), SwaggerInfov2)
|
||||
}
|
||||
@@ -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": "support@swagger.io"
|
||||
},
|
||||
"license": {
|
||||
"name": "Apache 2.0",
|
||||
"url": "http://www.apache.org/licenses/LICENSE-2.0.html"
|
||||
},
|
||||
"version": "2.0"
|
||||
},
|
||||
"basePath": "/v2",
|
||||
"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/v2.Book"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"definitions": {
|
||||
"v2.Book": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"author": {
|
||||
"type": "string"
|
||||
},
|
||||
"id": {
|
||||
"type": "integer"
|
||||
},
|
||||
"title": {
|
||||
"type": "string"
|
||||
},
|
||||
"year": {
|
||||
"type": "integer"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,42 @@
|
||||
basePath: /v2
|
||||
definitions:
|
||||
v2.Book:
|
||||
properties:
|
||||
author:
|
||||
type: string
|
||||
id:
|
||||
type: integer
|
||||
title:
|
||||
type: string
|
||||
year:
|
||||
type: integer
|
||||
type: object
|
||||
info:
|
||||
contact:
|
||||
email: support@swagger.io
|
||||
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: "2.0"
|
||||
paths:
|
||||
/books:
|
||||
get:
|
||||
consumes:
|
||||
- application/json
|
||||
description: get string by ID
|
||||
produces:
|
||||
- application/json
|
||||
responses:
|
||||
"200":
|
||||
description: ok
|
||||
schema:
|
||||
items:
|
||||
$ref: '#/definitions/v2.Book'
|
||||
type: array
|
||||
summary: Get a list of books in the the store
|
||||
swagger: "2.0"
|
||||
@@ -0,0 +1,26 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"github.com/gin-gonic/gin"
|
||||
swaggerFiles "github.com/swaggo/files"
|
||||
ginSwagger "github.com/swaggo/gin-swagger"
|
||||
v1 "github.com/swaggo/gin-swagger/example/multiple/api/v1"
|
||||
v2 "github.com/swaggo/gin-swagger/example/multiple/api/v2"
|
||||
_ "github.com/swaggo/gin-swagger/example/multiple/docs"
|
||||
)
|
||||
|
||||
func main() {
|
||||
// New gin router
|
||||
router := gin.New()
|
||||
|
||||
// Register api/v1 endpoints
|
||||
v1.Register(router)
|
||||
router.GET("/swagger/v1/*any", ginSwagger.WrapHandler(swaggerFiles.Handler, ginSwagger.InstanceName("v1")))
|
||||
|
||||
// Register api/v2 endpoints
|
||||
v2.Register(router)
|
||||
router.GET("/swagger/v2/*any", ginSwagger.WrapHandler(swaggerFiles.Handler, ginSwagger.InstanceName("v2")))
|
||||
|
||||
// Listen and Server in
|
||||
_ = router.Run()
|
||||
}
|
||||
Reference in New Issue
Block a user