From 0bb2c3942738c023153e02d32c96186d97573397 Mon Sep 17 00:00:00 2001 From: Bogdan U Date: Sun, 6 Feb 2022 11:18:16 +0200 Subject: [PATCH] chore: preserve compatibility with swagger (#194) --- example/basic/docs/docs.go | 71 +++------------- example/basic/docs/swagger.json | 130 ++++++++++++++++++++++++++++++ example/basic/docs/swagger.yaml | 87 ++++++++++++++++++++ example/gzipped/docs/docs.go | 44 ++++++++++ example/gzipped/docs/swagger.json | 21 +++++ example/gzipped/docs/swagger.yaml | 16 ++++ go.mod | 2 +- go.sum | 4 +- 8 files changed, 314 insertions(+), 61 deletions(-) create mode 100644 example/basic/docs/swagger.json create mode 100644 example/basic/docs/swagger.yaml create mode 100644 example/gzipped/docs/docs.go create mode 100644 example/gzipped/docs/swagger.json create mode 100644 example/gzipped/docs/swagger.yaml diff --git a/example/basic/docs/docs.go b/example/basic/docs/docs.go index 1159a0a..e445c8a 100644 --- a/example/basic/docs/docs.go +++ b/example/basic/docs/docs.go @@ -2,16 +2,9 @@ // This file was generated by swaggo/swag package docs -import ( - "bytes" - "encoding/json" - "strings" - "text/template" +import "github.com/swaggo/swag" - "github.com/swaggo/swag" -) - -var doc = `{ +const docTemplate_swagger = `{ "schemes": {{ marshal .Schemes }}, "swagger": "2.0", "info": { @@ -143,56 +136,18 @@ var doc = `{ } }` -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{ - Version: "1.0", - Host: "petstore.swagger.io: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 { - 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) - }, - "escape": func(v interface{}) string { - // escape tabs - str := strings.Replace(v.(string), "\t", "\\t", -1) - // replace " with \", and if that results in \\", replace that with \\\" - str = strings.Replace(str, "\"", "\\\"", -1) - return strings.Replace(str, "\\\\\"", "\\\\\\\"", -1) - }, - }).Parse(doc) - if err != nil { - return doc - } - - var tpl bytes.Buffer - if err := t.Execute(&tpl, sInfo); err != nil { - return doc - } - - return tpl.String() +// SwaggerInfo_swagger holds exported Swagger Info so clients can modify it +var SwaggerInfo_swagger = &swag.Spec{ + Version: "1.0", + Host: "petstore.swagger.io:8080", + BasePath: "/v2", + Schemes: []string{}, + Title: "Swagger Example API", + Description: "This is a sample server Petstore server.", + InfoInstanceName: "swagger", + SwaggerTemplate: docTemplate_swagger, } func init() { - swag.Register(swag.Name, &s{}) + swag.Register(SwaggerInfo_swagger.InstanceName(), SwaggerInfo_swagger) } diff --git a/example/basic/docs/swagger.json b/example/basic/docs/swagger.json new file mode 100644 index 0000000..91d599c --- /dev/null +++ b/example/basic/docs/swagger.json @@ -0,0 +1,130 @@ +{ + "swagger": "2.0", + "info": { + "description": "This is a sample server Petstore 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" + }, + "host": "petstore.swagger.io:8080", + "basePath": "/v2", + "paths": { + "/testapi/get-string-by-int/{some_id}": { + "get": { + "description": "get string by ID", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "summary": "Add a new pet to the store", + "parameters": [ + { + "type": "integer", + "description": "Some ID", + "name": "some_id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "ok", + "schema": { + "type": "string" + } + }, + "400": { + "description": "We need ID!!", + "schema": { + "$ref": "#/definitions/web.APIError" + } + }, + "404": { + "description": "Can not find ID", + "schema": { + "$ref": "#/definitions/web.APIError" + } + } + } + } + }, + "/testapi/get-struct-array-by-string/{some_id}": { + "get": { + "description": "get struct array by ID", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "parameters": [ + { + "type": "string", + "description": "Some ID", + "name": "some_id", + "in": "path", + "required": true + }, + { + "type": "integer", + "description": "Offset", + "name": "offset", + "in": "query", + "required": true + }, + { + "type": "integer", + "description": "Offset", + "name": "limit", + "in": "query", + "required": true + } + ], + "responses": { + "200": { + "description": "ok", + "schema": { + "type": "string" + } + }, + "400": { + "description": "We need ID!!", + "schema": { + "$ref": "#/definitions/web.APIError" + } + }, + "404": { + "description": "Can not find ID", + "schema": { + "$ref": "#/definitions/web.APIError" + } + } + } + } + } + }, + "definitions": { + "web.APIError": { + "type": "object", + "properties": { + "errorCode": { + "type": "integer" + }, + "errorMessage": { + "type": "string" + } + } + } + } +} \ No newline at end of file diff --git a/example/basic/docs/swagger.yaml b/example/basic/docs/swagger.yaml new file mode 100644 index 0000000..eb28805 --- /dev/null +++ b/example/basic/docs/swagger.yaml @@ -0,0 +1,87 @@ +basePath: /v2 +definitions: + web.APIError: + properties: + errorCode: + type: integer + errorMessage: + type: string + type: object +host: petstore.swagger.io:8080 +info: + contact: + email: support@swagger.io + name: API Support + url: http://www.swagger.io/support + description: This is a sample server Petstore 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: + /testapi/get-string-by-int/{some_id}: + get: + consumes: + - application/json + description: get string by ID + parameters: + - description: Some ID + in: path + name: some_id + required: true + type: integer + produces: + - application/json + responses: + "200": + description: ok + schema: + type: string + "400": + description: We need ID!! + schema: + $ref: '#/definitions/web.APIError' + "404": + description: Can not find ID + schema: + $ref: '#/definitions/web.APIError' + summary: Add a new pet to the store + /testapi/get-struct-array-by-string/{some_id}: + get: + consumes: + - application/json + description: get struct array by ID + parameters: + - description: Some ID + in: path + name: some_id + required: true + type: string + - description: Offset + in: query + name: offset + required: true + type: integer + - description: Offset + in: query + name: limit + required: true + type: integer + produces: + - application/json + responses: + "200": + description: ok + schema: + type: string + "400": + description: We need ID!! + schema: + $ref: '#/definitions/web.APIError' + "404": + description: Can not find ID + schema: + $ref: '#/definitions/web.APIError' +swagger: "2.0" diff --git a/example/gzipped/docs/docs.go b/example/gzipped/docs/docs.go new file mode 100644 index 0000000..b47edb2 --- /dev/null +++ b/example/gzipped/docs/docs.go @@ -0,0 +1,44 @@ +// Package docs GENERATED BY THE COMMAND ABOVE; DO NOT EDIT +// This file was generated by swaggo/swag +package docs + +import "github.com/swaggo/swag" + +const docTemplate_swagger = `{ + "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": {} +}` + +// SwaggerInfo_swagger holds exported Swagger Info so clients can modify it +var SwaggerInfo_swagger = &swag.Spec{ + Version: "1.0", + Host: "petstore.swagger.io", + BasePath: "/v2", + Schemes: []string{}, + Title: "Swagger Example API", + Description: "This is a sample server Petstore server.", + InfoInstanceName: "swagger", + SwaggerTemplate: docTemplate_swagger, +} + +func init() { + swag.Register(SwaggerInfo_swagger.InstanceName(), SwaggerInfo_swagger) +} diff --git a/example/gzipped/docs/swagger.json b/example/gzipped/docs/swagger.json new file mode 100644 index 0000000..70f0598 --- /dev/null +++ b/example/gzipped/docs/swagger.json @@ -0,0 +1,21 @@ +{ + "swagger": "2.0", + "info": { + "description": "This is a sample server Petstore 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" + }, + "host": "petstore.swagger.io", + "basePath": "/v2", + "paths": {} +} \ No newline at end of file diff --git a/example/gzipped/docs/swagger.yaml b/example/gzipped/docs/swagger.yaml new file mode 100644 index 0000000..eb6cf35 --- /dev/null +++ b/example/gzipped/docs/swagger.yaml @@ -0,0 +1,16 @@ +basePath: /v2 +host: petstore.swagger.io +info: + contact: + email: support@swagger.io + name: API Support + url: http://www.swagger.io/support + description: This is a sample server Petstore 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: {} +swagger: "2.0" diff --git a/go.mod b/go.mod index 830bc6f..037202a 100644 --- a/go.mod +++ b/go.mod @@ -7,6 +7,6 @@ require ( github.com/gin-gonic/gin v1.7.7 github.com/stretchr/testify v1.7.0 github.com/swaggo/files v0.0.0-20210815190702-a29dd2bc99b2 - github.com/swaggo/swag v1.7.8 + github.com/swaggo/swag v1.7.9 golang.org/x/net v0.0.0-20220127200216-cd36cc0744dd ) diff --git a/go.sum b/go.sum index 81f4308..9d4d45e 100644 --- a/go.sum +++ b/go.sum @@ -90,8 +90,8 @@ github.com/stretchr/testify v1.7.0 h1:nwc3DEeHmmLAfoZucVR881uASk0Mfjw8xYJ99tb5Cc github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg= github.com/swaggo/files v0.0.0-20210815190702-a29dd2bc99b2 h1:+iNTcqQJy0OZ5jk6a5NLib47eqXK8uYcPX+O4+cBpEM= github.com/swaggo/files v0.0.0-20210815190702-a29dd2bc99b2/go.mod h1:lKJPbtWzJ9JhsTN1k1gZgleJWY/cqq0psdoMmaThG3w= -github.com/swaggo/swag v1.7.8 h1:w249t0l/kc/DKMGlS0fppNJQxKyJ8heNaUWB6nsH3zc= -github.com/swaggo/swag v1.7.8/go.mod h1:gZ+TJ2w/Ve1RwQsA2IRoSOTidHz6DX+PIG8GWvbnoLU= +github.com/swaggo/swag v1.7.9 h1:6vCG5mm43ebDzGlZPMGYrYI4zKFfOr5kicQX8qjeDwc= +github.com/swaggo/swag v1.7.9/go.mod h1:gZ+TJ2w/Ve1RwQsA2IRoSOTidHz6DX+PIG8GWvbnoLU= github.com/ugorji/go v1.1.7 h1:/68gy2h+1mWMrwZFeD1kQialdSzAb432dtpeJ42ovdo= github.com/ugorji/go v1.1.7/go.mod h1:kZn38zHttfInRq0xu/PH0az30d+z6vm202qpg1oXVMw= github.com/ugorji/go/codec v1.1.7 h1:2SvQaVZ1ouYrrKKwoSk2pzd4A9evlKJb9oTL+OaLUSs=