├── .github ├── CODEOWNERS ├── dependabot.yml └── workflows │ └── test-builds.yml ├── testdata ├── empty.json ├── empty-route-schema.json ├── router_with_prefix.json ├── tags.json ├── extension.json ├── users-deprecated-with-description.json ├── security.json ├── query.json ├── subrouter.json ├── headers.json ├── cookies.json ├── schema-no-content.json ├── params.json ├── multipart-requestbody.json ├── params-autofill.json ├── allof.json ├── anyof.json ├── oneOf.json ├── users_employees.yaml └── users_employees.json ├── apirouter ├── router.go ├── transformpath.go └── transformpath_test.go ├── .gitignore ├── Makefile ├── support ├── testdata │ ├── integration.json │ └── intergation-subrouter.json ├── fiber │ ├── fiber.go │ ├── fiber_test.go │ └── integration_test.go ├── echo │ ├── echo.go │ ├── echo_test.go │ └── integration_test.go └── gorilla │ ├── gorilla.go │ ├── gorilla_test.go │ ├── examples_test.go │ ├── integration_test.go │ └── testdata │ └── examples-users.json ├── LICENSE ├── operation.go ├── go.mod ├── operation_test.go ├── CHANGELOG.md ├── main.go ├── README.md ├── go.sum ├── route.go ├── main_test.go └── route_test.go /.github/CODEOWNERS: -------------------------------------------------------------------------------- 1 | * @davidebianchi 2 | -------------------------------------------------------------------------------- /.github/dependabot.yml: -------------------------------------------------------------------------------- 1 | version: 2 2 | updates: 3 | - package-ecosystem: gomod 4 | directory: "/" 5 | schedule: 6 | interval: daily 7 | open-pull-requests-limit: 10 8 | -------------------------------------------------------------------------------- /testdata/empty.json: -------------------------------------------------------------------------------- 1 | { 2 | "info": { 3 | "title": "test openapi title", 4 | "version": "test openapi version" 5 | }, 6 | "openapi": "3.0.0", 7 | "paths": {} 8 | } 9 | -------------------------------------------------------------------------------- /apirouter/router.go: -------------------------------------------------------------------------------- 1 | package apirouter 2 | 3 | type Router[HandlerFunc any, Route any] interface { 4 | AddRoute(method string, path string, handler HandlerFunc) Route 5 | SwaggerHandler(contentType string, blob []byte) HandlerFunc 6 | TransformPathToOasPath(path string) string 7 | } 8 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # Binaries for programs and plugins 2 | *.exe 3 | *.exe~ 4 | *.dll 5 | *.so 6 | *.dylib 7 | 8 | # Test binary, built with `go test -c` 9 | *.test 10 | 11 | # Output of the go coverage tool, specifically when used with LiteIDE 12 | *.out 13 | 14 | # Dependency directories (remove the comment below to include it) 15 | # vendor/ 16 | -------------------------------------------------------------------------------- /testdata/empty-route-schema.json: -------------------------------------------------------------------------------- 1 | { 2 | "info": { 3 | "title": "test openapi title", 4 | "version": "test openapi version" 5 | }, 6 | "openapi": "3.0.0", 7 | "paths": { 8 | "/": { 9 | "post": { 10 | "responses": { 11 | "default": { 12 | "description": "" 13 | } 14 | } 15 | } 16 | } 17 | } 18 | } 19 | -------------------------------------------------------------------------------- /testdata/router_with_prefix.json: -------------------------------------------------------------------------------- 1 | { 2 | "info": { 3 | "title": "test openapi title", 4 | "version": "test openapi version" 5 | }, 6 | "openapi": "3.0.0", 7 | "paths": { 8 | "/prefix/foo": { 9 | "get": { 10 | "responses": { 11 | "default": { 12 | "description": "" 13 | } 14 | } 15 | } 16 | } 17 | } 18 | } 19 | -------------------------------------------------------------------------------- /apirouter/transformpath.go: -------------------------------------------------------------------------------- 1 | package apirouter 2 | 3 | import ( 4 | "strings" 5 | ) 6 | 7 | func TransformPathParamsWithColon(path string) string { 8 | pathParams := strings.Split(path, "/") 9 | for i, param := range pathParams { 10 | if strings.HasPrefix(param, ":") { 11 | pathParams[i] = strings.Replace(param, ":", "{", 1) + "}" 12 | } 13 | } 14 | return strings.Join(pathParams, "/") 15 | } 16 | -------------------------------------------------------------------------------- /testdata/tags.json: -------------------------------------------------------------------------------- 1 | { 2 | "info": { 3 | "title": "test openapi title", 4 | "version": "test openapi version" 5 | }, 6 | "openapi": "3.0.0", 7 | "paths": { 8 | "/users": { 9 | "get": { 10 | "tags": ["Tag1", "Tag2"], 11 | "responses": { 12 | "default": { 13 | "description": "" 14 | } 15 | } 16 | } 17 | } 18 | } 19 | } 20 | -------------------------------------------------------------------------------- /testdata/extension.json: -------------------------------------------------------------------------------- 1 | { 2 | "info": { 3 | "title": "test openapi title", 4 | "version": "test openapi version" 5 | }, 6 | "openapi": "3.0.0", 7 | "paths": { 8 | "/users": { 9 | "get": { 10 | "responses": { 11 | "default": { 12 | "description": "" 13 | } 14 | }, 15 | "x-extension-field": { 16 | "foo": "bar" 17 | } 18 | } 19 | } 20 | } 21 | } 22 | -------------------------------------------------------------------------------- /testdata/users-deprecated-with-description.json: -------------------------------------------------------------------------------- 1 | { 2 | "info": { 3 | "title": "test openapi title", 4 | "version": "test openapi version" 5 | }, 6 | "openapi": "3.0.0", 7 | "paths": { 8 | "/users": { 9 | "get": { 10 | "deprecated": true, 11 | "description": "this is the long route description", 12 | "responses": { 13 | "default": { 14 | "description": "" 15 | } 16 | }, 17 | "summary": "small description" 18 | } 19 | } 20 | } 21 | } 22 | -------------------------------------------------------------------------------- /testdata/security.json: -------------------------------------------------------------------------------- 1 | { 2 | "info": { 3 | "title": "test openapi title", 4 | "version": "test openapi version" 5 | }, 6 | "openapi": "3.0.0", 7 | "paths": { 8 | "/users": { 9 | "get": { 10 | "responses": { 11 | "default": { 12 | "description": "" 13 | } 14 | }, 15 | "security": [ 16 | { 17 | "api_key": [], 18 | "auth": [ 19 | "resource.write" 20 | ] 21 | } 22 | ] 23 | } 24 | } 25 | } 26 | } 27 | -------------------------------------------------------------------------------- /testdata/query.json: -------------------------------------------------------------------------------- 1 | { 2 | "info": { 3 | "title": "test openapi title", 4 | "version": "test openapi version" 5 | }, 6 | "openapi": "3.0.0", 7 | "paths": { 8 | "/projects": { 9 | "get": { 10 | "parameters": [ 11 | { 12 | "description": "projectId is the project id", 13 | "in": "query", 14 | "name": "projectId", 15 | "schema": { 16 | "type": "string" 17 | } 18 | } 19 | ], 20 | "responses": { 21 | "default": { 22 | "description": "" 23 | } 24 | } 25 | } 26 | } 27 | } 28 | } 29 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | VERSION ?= latest 2 | 3 | # Create a variable that contains the current date in UTC 4 | # Different flow if this script is running on Darwin or Linux machines. 5 | ifeq (Darwin,$(shell uname)) 6 | NOW_DATE = $(shell date -u +%d-%m-%Y) 7 | else 8 | NOW_DATE = $(shell date -u -I) 9 | endif 10 | 11 | all: test 12 | 13 | .PHONY: test 14 | test: 15 | go test ./... -coverprofile coverage.out 16 | 17 | .PHONY: version 18 | version: 19 | sed -i.bck "s|## Unreleased|## Unreleased\n\n## ${VERSION} - ${NOW_DATE}|g" "CHANGELOG.md" 20 | rm -fr "CHANGELOG.md.bck" 21 | git add "CHANGELOG.md" 22 | git commit -m "Upgrade version to v${VERSION}" 23 | git tag v${VERSION} 24 | -------------------------------------------------------------------------------- /testdata/subrouter.json: -------------------------------------------------------------------------------- 1 | { 2 | "info": { 3 | "title": "test openapi title", 4 | "version": "test openapi version" 5 | }, 6 | "openapi": "3.0.0", 7 | "paths": { 8 | "/foo": { 9 | "get": { 10 | "responses": { 11 | "default": { 12 | "description": "" 13 | } 14 | } 15 | } 16 | }, 17 | "/prefix/taz": { 18 | "get": { 19 | "responses": { 20 | "default": { 21 | "description": "" 22 | } 23 | } 24 | } 25 | }, 26 | "/prefix": { 27 | "get": { 28 | "responses": { 29 | "default": { 30 | "description": "" 31 | } 32 | } 33 | } 34 | } 35 | } 36 | } 37 | -------------------------------------------------------------------------------- /testdata/headers.json: -------------------------------------------------------------------------------- 1 | { 2 | "info": { 3 | "title": "test openapi title", 4 | "version": "test openapi version" 5 | }, 6 | "openapi": "3.0.0", 7 | "paths": { 8 | "/projects": { 9 | "get": { 10 | "parameters": [ 11 | { 12 | "in": "header", 13 | "name": "bar", 14 | "schema": { 15 | "type": "string" 16 | } 17 | }, 18 | { 19 | "description": "foo description", 20 | "in": "header", 21 | "name": "foo", 22 | "schema": { 23 | "type": "string" 24 | } 25 | } 26 | ], 27 | "responses": { 28 | "default": { 29 | "description": "" 30 | } 31 | } 32 | } 33 | } 34 | } 35 | } 36 | -------------------------------------------------------------------------------- /support/testdata/integration.json: -------------------------------------------------------------------------------- 1 | { 2 | "info": { 3 | "title": "test openapi title", 4 | "version": "test openapi version" 5 | }, 6 | "openapi": "3.0.0", 7 | "paths": { 8 | "/hello": { 9 | "get": { 10 | "responses": { 11 | "default": { 12 | "description": "" 13 | } 14 | } 15 | } 16 | }, 17 | "/hello/{value}": { 18 | "post": { 19 | "parameters": [ 20 | { 21 | "in": "path", 22 | "name": "value", 23 | "required": true, 24 | "schema": { 25 | "type": "string" 26 | } 27 | } 28 | ], 29 | "responses": { 30 | "default": { 31 | "description": "" 32 | } 33 | } 34 | } 35 | } 36 | } 37 | } 38 | -------------------------------------------------------------------------------- /testdata/cookies.json: -------------------------------------------------------------------------------- 1 | { 2 | "info": { 3 | "title": "test openapi title", 4 | "version": "test openapi version" 5 | }, 6 | "openapi": "3.0.0", 7 | "paths": { 8 | "/projects": { 9 | "get": { 10 | "parameters": [ 11 | { 12 | "in": "cookie", 13 | "name": "csrftoken", 14 | "schema": { 15 | "type": "string" 16 | } 17 | }, 18 | { 19 | "description": "boolean. Set 0 to disable and 1 to enable", 20 | "in": "cookie", 21 | "name": "debug", 22 | "schema": { 23 | "type": "integer" 24 | } 25 | } 26 | ], 27 | "responses": { 28 | "default": { 29 | "description": "" 30 | } 31 | } 32 | } 33 | } 34 | } 35 | } 36 | -------------------------------------------------------------------------------- /support/fiber/fiber.go: -------------------------------------------------------------------------------- 1 | package fiber 2 | 3 | import ( 4 | "github.com/davidebianchi/gswagger/apirouter" 5 | "github.com/gofiber/fiber/v2" 6 | ) 7 | 8 | type HandlerFunc = fiber.Handler 9 | type Route = fiber.Router 10 | 11 | type fiberRouter struct { 12 | router fiber.Router 13 | } 14 | 15 | func NewRouter(router fiber.Router) apirouter.Router[HandlerFunc, Route] { 16 | return fiberRouter{ 17 | router: router, 18 | } 19 | } 20 | 21 | func (r fiberRouter) AddRoute(method string, path string, handler HandlerFunc) Route { 22 | return r.router.Add(method, path, handler) 23 | } 24 | 25 | func (r fiberRouter) SwaggerHandler(contentType string, blob []byte) HandlerFunc { 26 | return func(c *fiber.Ctx) error { 27 | c.Set("Content-Type", contentType) 28 | return c.Send(blob) 29 | } 30 | } 31 | 32 | func (r fiberRouter) TransformPathToOasPath(path string) string { 33 | return apirouter.TransformPathParamsWithColon(path) 34 | } 35 | -------------------------------------------------------------------------------- /support/echo/echo.go: -------------------------------------------------------------------------------- 1 | package echo 2 | 3 | import ( 4 | "github.com/davidebianchi/gswagger/apirouter" 5 | 6 | "net/http" 7 | 8 | "github.com/labstack/echo/v4" 9 | ) 10 | 11 | type Route = *echo.Route 12 | 13 | type echoRouter struct { 14 | router *echo.Echo 15 | } 16 | 17 | func (r echoRouter) AddRoute(method string, path string, handler echo.HandlerFunc) Route { 18 | return r.router.Add(method, path, handler) 19 | } 20 | 21 | func (r echoRouter) SwaggerHandler(contentType string, blob []byte) echo.HandlerFunc { 22 | return func(c echo.Context) error { 23 | c.Response().Header().Add("Content-Type", contentType) 24 | return c.JSONBlob(http.StatusOK, blob) 25 | } 26 | } 27 | 28 | func (r echoRouter) TransformPathToOasPath(path string) string { 29 | return apirouter.TransformPathParamsWithColon(path) 30 | } 31 | 32 | func NewRouter(router *echo.Echo) apirouter.Router[echo.HandlerFunc, Route] { 33 | return echoRouter{ 34 | router: router, 35 | } 36 | } 37 | -------------------------------------------------------------------------------- /support/testdata/intergation-subrouter.json: -------------------------------------------------------------------------------- 1 | { 2 | "info": { 3 | "title": "test openapi title", 4 | "version": "test openapi version" 5 | }, 6 | "openapi": "3.0.0", 7 | "paths": { 8 | "/hello": { 9 | "get": { 10 | "responses": { 11 | "default": { 12 | "description": "" 13 | } 14 | } 15 | } 16 | }, 17 | "/hello/{value}": { 18 | "post": { 19 | "parameters": [ 20 | { 21 | "in": "path", 22 | "name": "value", 23 | "required": true, 24 | "schema": { 25 | "type": "string" 26 | } 27 | } 28 | ], 29 | "responses": { 30 | "default": { 31 | "description": "" 32 | } 33 | } 34 | } 35 | }, 36 | "/prefix/foo": { 37 | "get": { 38 | "responses": { 39 | "default": { 40 | "description": "" 41 | } 42 | } 43 | } 44 | } 45 | } 46 | } 47 | -------------------------------------------------------------------------------- /testdata/schema-no-content.json: -------------------------------------------------------------------------------- 1 | { 2 | "info": { 3 | "title": "test openapi title", 4 | "version": "test openapi version" 5 | }, 6 | "openapi": "3.0.0", 7 | "paths": { 8 | "/{id}": { 9 | "post": { 10 | "parameters": [ 11 | { 12 | "in": "path", 13 | "name": "id", 14 | "required": true, 15 | "schema": {} 16 | }, 17 | { 18 | "in": "query", 19 | "name": "q", 20 | "schema": {} 21 | }, 22 | { 23 | "in": "header", 24 | "name": "key", 25 | "schema": {} 26 | }, 27 | { 28 | "in": "cookie", 29 | "name": "cookie1", 30 | "schema": {} 31 | } 32 | ], 33 | "requestBody": { 34 | "content": {}, 35 | "description": "request body without schema" 36 | }, 37 | "responses": { 38 | "204": { 39 | "description": "" 40 | } 41 | } 42 | } 43 | } 44 | } 45 | } 46 | -------------------------------------------------------------------------------- /support/gorilla/gorilla.go: -------------------------------------------------------------------------------- 1 | package gorilla 2 | 3 | import ( 4 | "github.com/davidebianchi/gswagger/apirouter" 5 | 6 | "net/http" 7 | 8 | "github.com/gorilla/mux" 9 | ) 10 | 11 | // HandlerFunc is the http type handler used by gorilla/mux 12 | type HandlerFunc func(w http.ResponseWriter, req *http.Request) 13 | type Route = *mux.Route 14 | 15 | type gorillaRouter struct { 16 | router *mux.Router 17 | } 18 | 19 | func (r gorillaRouter) AddRoute(method string, path string, handler HandlerFunc) Route { 20 | return r.router.HandleFunc(path, handler).Methods(method) 21 | } 22 | 23 | func (r gorillaRouter) SwaggerHandler(contentType string, blob []byte) HandlerFunc { 24 | return func(w http.ResponseWriter, req *http.Request) { 25 | w.Header().Set("Content-Type", contentType) 26 | w.WriteHeader(http.StatusOK) 27 | w.Write(blob) 28 | } 29 | } 30 | 31 | func (r gorillaRouter) TransformPathToOasPath(path string) string { 32 | return path 33 | } 34 | 35 | func NewRouter(router *mux.Router) apirouter.Router[HandlerFunc, Route] { 36 | return gorillaRouter{ 37 | router: router, 38 | } 39 | } 40 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2020 Davide Bianchi 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /testdata/params.json: -------------------------------------------------------------------------------- 1 | { 2 | "info": { 3 | "title": "test openapi title", 4 | "version": "test openapi version" 5 | }, 6 | "openapi": "3.0.0", 7 | "paths": { 8 | "/cars/{carId}/drivers/{driverId}": { 9 | "get": { 10 | "parameters": [ 11 | { 12 | "in": "path", 13 | "name": "carId", 14 | "required": true, 15 | "schema": { 16 | "type": "string" 17 | } 18 | }, 19 | { 20 | "in": "path", 21 | "name": "driverId", 22 | "required": true, 23 | "schema": { 24 | "type": "string" 25 | } 26 | } 27 | ], 28 | "responses": { 29 | "default": { 30 | "description": "" 31 | } 32 | } 33 | } 34 | }, 35 | "/users/{userId}": { 36 | "get": { 37 | "parameters": [ 38 | { 39 | "description": "userId is a number above 0", 40 | "in": "path", 41 | "name": "userId", 42 | "required": true, 43 | "schema": { 44 | "type": "integer" 45 | } 46 | } 47 | ], 48 | "responses": { 49 | "default": { 50 | "description": "" 51 | } 52 | } 53 | } 54 | } 55 | } 56 | } 57 | -------------------------------------------------------------------------------- /apirouter/transformpath_test.go: -------------------------------------------------------------------------------- 1 | package apirouter 2 | 3 | import ( 4 | "testing" 5 | 6 | "github.com/stretchr/testify/require" 7 | ) 8 | 9 | func TestTransformPathParamsWithColon(t *testing.T) { 10 | testCases := []struct { 11 | name string 12 | path string 13 | expectedPath string 14 | }{ 15 | { 16 | name: "only /", 17 | path: "/", 18 | expectedPath: "/", 19 | }, 20 | { 21 | name: "without params", 22 | path: "/foo", 23 | expectedPath: "/foo", 24 | }, 25 | { 26 | name: "without params ending with /", 27 | path: "/foo/", 28 | expectedPath: "/foo/", 29 | }, 30 | { 31 | name: "with params", 32 | path: "/foo/:par1", 33 | expectedPath: "/foo/{par1}", 34 | }, 35 | { 36 | name: "with params ending with /", 37 | path: "/foo/:par1/", 38 | expectedPath: "/foo/{par1}/", 39 | }, 40 | { 41 | name: "with multiple params", 42 | path: "/:par1/:par2/:par3", 43 | expectedPath: "/{par1}/{par2}/{par3}", 44 | }, 45 | { 46 | name: "with multiple params ending with /", 47 | path: "/:par1/:par2/:par3/", 48 | expectedPath: "/{par1}/{par2}/{par3}/", 49 | }, 50 | } 51 | 52 | for _, test := range testCases { 53 | t.Run(test.name, func(t *testing.T) { 54 | actual := TransformPathParamsWithColon(test.path) 55 | 56 | require.Equal(t, test.expectedPath, actual) 57 | }) 58 | } 59 | } 60 | -------------------------------------------------------------------------------- /.github/workflows/test-builds.yml: -------------------------------------------------------------------------------- 1 | name: Test and build 2 | on: 3 | pull_request: 4 | types: [opened] 5 | push: 6 | jobs: 7 | tests: 8 | name: Test on go ${{ matrix.go_version }} os ${{ matrix.os }} 9 | runs-on: ${{ matrix.os }} 10 | strategy: 11 | matrix: 12 | go_version: ['1.24', '1.25'] 13 | os: [ubuntu-latest] 14 | include: 15 | - go_version: '1.25' 16 | os: macos-latest 17 | steps: 18 | - uses: actions/checkout@v1 19 | - name: Use golang ${{ matrix.go_version }} 20 | uses: actions/setup-go@v1 21 | with: 22 | go-version: ${{ matrix.go_version }} 23 | 24 | - name: Go version 25 | run: | 26 | go version 27 | - name: Go get dependencies 28 | run: | 29 | go get -v -t -d ./... 30 | - name: Run tests 31 | run: | 32 | go test ./... -count=1 -race -cover -coverprofile cover.out 33 | - name: Build 34 | run: | 35 | go build -v . 36 | - name: Send the coverage output 37 | uses: shogo82148/actions-goveralls@v1 38 | with: 39 | path-to-profile: cover.out 40 | flag-name: Go-${{ matrix.go_version }} 41 | parallel: true 42 | 43 | post-tests: 44 | runs-on: ubuntu-latest 45 | needs: tests 46 | steps: 47 | - name: Close coverage report 48 | uses: shogo82148/actions-goveralls@v1 49 | with: 50 | parallel-finished: true 51 | -------------------------------------------------------------------------------- /testdata/multipart-requestbody.json: -------------------------------------------------------------------------------- 1 | { 2 | "info": { 3 | "title": "test openapi title", 4 | "version": "test openapi version" 5 | }, 6 | "openapi": "3.0.0", 7 | "paths": { 8 | "/files": { 9 | "post": { 10 | "requestBody": { 11 | "description": "upload file", 12 | "content": { 13 | "multipart/form-data": { 14 | "schema": { 15 | "type": "object", 16 | "properties": { 17 | "id": { 18 | "type": "string" 19 | }, 20 | "address": { 21 | "type": "object", 22 | "properties": { 23 | "street": { 24 | "type": "string" 25 | }, 26 | "city": { 27 | "type": "string" 28 | } 29 | } 30 | }, 31 | "profileImage": { 32 | "type": "string", 33 | "format": "binary" 34 | } 35 | } 36 | } 37 | } 38 | } 39 | }, 40 | "responses": { 41 | "200": { 42 | "description": "", 43 | "content": { 44 | "application/json": { 45 | "schema": { 46 | "type": "string" 47 | } 48 | } 49 | } 50 | } 51 | } 52 | } 53 | } 54 | } 55 | } 56 | -------------------------------------------------------------------------------- /operation.go: -------------------------------------------------------------------------------- 1 | package swagger 2 | 3 | import ( 4 | "github.com/getkin/kin-openapi/openapi3" 5 | ) 6 | 7 | // Operation type 8 | type Operation struct { 9 | *openapi3.Operation 10 | } 11 | 12 | // NewOperation returns an OpenApi operation. 13 | func NewOperation() Operation { 14 | return Operation{ 15 | openapi3.NewOperation(), 16 | } 17 | } 18 | 19 | // AddRequestBody set request body into operation. 20 | func (o *Operation) AddRequestBody(requestBody *openapi3.RequestBody) { 21 | o.RequestBody = &openapi3.RequestBodyRef{ 22 | Value: requestBody, 23 | } 24 | } 25 | 26 | // AddResponse add response to operation. It check if the description is present 27 | // (otherwise default to empty string). This method does not add the default response, 28 | // but it is always possible to add it manually. 29 | func (o *Operation) AddResponse(status int, response *openapi3.Response) { 30 | if o.Responses == nil { 31 | o.Responses = &openapi3.Responses{} 32 | } 33 | if response.Description == nil { 34 | // a description is required by kin openapi, so we set an empty description 35 | // if it is not given. 36 | response.WithDescription("") 37 | } 38 | o.Operation.AddResponse(status, response) 39 | } 40 | 41 | func (o *Operation) addSecurityRequirements(securityRequirements SecurityRequirements) { 42 | if securityRequirements != nil && o.Security == nil { 43 | o.Security = openapi3.NewSecurityRequirements() 44 | } 45 | for _, securityRequirement := range securityRequirements { 46 | o.Security.With(openapi3.SecurityRequirement(securityRequirement)) 47 | } 48 | } 49 | -------------------------------------------------------------------------------- /support/fiber/fiber_test.go: -------------------------------------------------------------------------------- 1 | package fiber 2 | 3 | import ( 4 | "io" 5 | "net/http" 6 | "net/http/httptest" 7 | "testing" 8 | 9 | "github.com/davidebianchi/gswagger/apirouter" 10 | 11 | "github.com/gofiber/fiber/v2" 12 | "github.com/stretchr/testify/require" 13 | ) 14 | 15 | func TestFiberRouterSupport(t *testing.T) { 16 | fiberRouter := fiber.New() 17 | ar := NewRouter(fiberRouter) 18 | 19 | t.Run("create a new api router", func(t *testing.T) { 20 | require.Implements(t, (*apirouter.Router[HandlerFunc, Route])(nil), ar) 21 | }) 22 | 23 | t.Run("add new route", func(t *testing.T) { 24 | route := ar.AddRoute(http.MethodGet, "/foo", func(c *fiber.Ctx) error { 25 | return c.SendStatus(http.StatusOK) 26 | }) 27 | require.IsType(t, route, fiber.New()) 28 | 29 | t.Run("router exposes correctly api", func(t *testing.T) { 30 | r := httptest.NewRequest(http.MethodGet, "/foo", nil) 31 | 32 | resp, err := fiberRouter.Test(r) 33 | require.NoError(t, err) 34 | require.Equal(t, http.StatusOK, resp.StatusCode) 35 | }) 36 | 37 | t.Run("router exposes api only to the specific method", func(t *testing.T) { 38 | r := httptest.NewRequest(http.MethodPost, "/foo", nil) 39 | 40 | resp, err := fiberRouter.Test(r) 41 | require.NoError(t, err) 42 | require.Equal(t, http.StatusMethodNotAllowed, resp.StatusCode) 43 | }) 44 | }) 45 | 46 | t.Run("create openapi handler", func(t *testing.T) { 47 | handlerFunc := ar.SwaggerHandler("text/html", []byte("some data")) 48 | fiberRouter.Get("/oas", handlerFunc) 49 | 50 | t.Run("responds correctly to the API", func(t *testing.T) { 51 | r := httptest.NewRequest(http.MethodGet, "/oas", nil) 52 | 53 | resp, err := fiberRouter.Test(r) 54 | require.NoError(t, err) 55 | require.Equal(t, http.StatusOK, resp.StatusCode) 56 | require.Equal(t, "text/html", resp.Header.Get("Content-Type")) 57 | 58 | body, err := io.ReadAll(resp.Body) 59 | require.NoError(t, err) 60 | require.Equal(t, "some data", string(body)) 61 | }) 62 | }) 63 | } 64 | -------------------------------------------------------------------------------- /go.mod: -------------------------------------------------------------------------------- 1 | module github.com/davidebianchi/gswagger 2 | 3 | go 1.24 4 | 5 | require ( 6 | github.com/getkin/kin-openapi v0.131.0 7 | github.com/ghodss/yaml v1.0.0 8 | github.com/gofiber/fiber/v2 v2.52.5 9 | github.com/gorilla/mux v1.8.1 10 | github.com/invopop/jsonschema v0.12.0 11 | github.com/labstack/echo/v4 v4.12.0 12 | github.com/stretchr/testify v1.9.0 13 | ) 14 | 15 | require ( 16 | github.com/andybalholm/brotli v1.0.5 // indirect 17 | github.com/bahlo/generic-list-go v0.2.0 // indirect 18 | github.com/buger/jsonparser v1.1.1 // indirect 19 | github.com/davecgh/go-spew v1.1.1 // indirect 20 | github.com/go-openapi/jsonpointer v0.21.0 // indirect 21 | github.com/go-openapi/swag v0.23.0 // indirect 22 | github.com/google/uuid v1.5.0 // indirect 23 | github.com/josharian/intern v1.0.0 // indirect 24 | github.com/klauspost/compress v1.17.0 // indirect 25 | github.com/labstack/gommon v0.4.2 // indirect 26 | github.com/mailru/easyjson v0.7.7 // indirect 27 | github.com/mattn/go-colorable v0.1.13 // indirect 28 | github.com/mattn/go-isatty v0.0.20 // indirect 29 | github.com/mattn/go-runewidth v0.0.15 // indirect 30 | github.com/mohae/deepcopy v0.0.0-20170929034955-c48cc78d4826 // indirect 31 | github.com/oasdiff/yaml v0.0.0-20250309154309-f31be36b4037 // indirect 32 | github.com/oasdiff/yaml3 v0.0.0-20250309153720-d2182401db90 // indirect 33 | github.com/perimeterx/marshmallow v1.1.5 // indirect 34 | github.com/pmezard/go-difflib v1.0.0 // indirect 35 | github.com/rivo/uniseg v0.2.0 // indirect 36 | github.com/valyala/bytebufferpool v1.0.0 // indirect 37 | github.com/valyala/fasthttp v1.51.0 // indirect 38 | github.com/valyala/fasttemplate v1.2.2 // indirect 39 | github.com/valyala/tcplisten v1.0.0 // indirect 40 | github.com/wk8/go-ordered-map/v2 v2.1.8 // indirect 41 | golang.org/x/crypto v0.22.0 // indirect 42 | golang.org/x/net v0.24.0 // indirect 43 | golang.org/x/sys v0.19.0 // indirect 44 | golang.org/x/text v0.14.0 // indirect 45 | gopkg.in/yaml.v2 v2.4.0 // indirect 46 | gopkg.in/yaml.v3 v3.0.1 // indirect 47 | ) 48 | -------------------------------------------------------------------------------- /support/echo/echo_test.go: -------------------------------------------------------------------------------- 1 | package echo 2 | 3 | import ( 4 | "io" 5 | "net/http" 6 | "net/http/httptest" 7 | "testing" 8 | 9 | "github.com/davidebianchi/gswagger/apirouter" 10 | "github.com/labstack/echo/v4" 11 | "github.com/stretchr/testify/require" 12 | ) 13 | 14 | func TestGorillaMuxRouter(t *testing.T) { 15 | echoRouter := echo.New() 16 | ar := NewRouter(echoRouter) 17 | 18 | t.Run("create a new api router", func(t *testing.T) { 19 | require.Implements(t, (*apirouter.Router[echo.HandlerFunc, Route])(nil), ar) 20 | }) 21 | 22 | t.Run("add new route", func(t *testing.T) { 23 | route := ar.AddRoute(http.MethodGet, "/foo", func(c echo.Context) error { 24 | return c.String(http.StatusOK, "") 25 | }) 26 | require.IsType(t, route, &echo.Route{}) 27 | 28 | t.Run("router exposes correctly api", func(t *testing.T) { 29 | w := httptest.NewRecorder() 30 | r := httptest.NewRequest(http.MethodGet, "/foo", nil) 31 | 32 | echoRouter.ServeHTTP(w, r) 33 | 34 | require.Equal(t, http.StatusOK, w.Result().StatusCode) 35 | }) 36 | 37 | t.Run("router exposes api only to the specific method", func(t *testing.T) { 38 | w := httptest.NewRecorder() 39 | r := httptest.NewRequest(http.MethodPost, "/foo", nil) 40 | 41 | echoRouter.ServeHTTP(w, r) 42 | 43 | require.Equal(t, http.StatusMethodNotAllowed, w.Result().StatusCode) 44 | }) 45 | }) 46 | 47 | t.Run("create openapi handler", func(t *testing.T) { 48 | handlerFunc := ar.SwaggerHandler("text/html", []byte("some data")) 49 | echoRouter.GET("/oas", handlerFunc) 50 | 51 | t.Run("responds correctly to the API", func(t *testing.T) { 52 | w := httptest.NewRecorder() 53 | r := httptest.NewRequest(http.MethodGet, "/oas", nil) 54 | 55 | echoRouter.ServeHTTP(w, r) 56 | 57 | require.Equal(t, http.StatusOK, w.Result().StatusCode) 58 | require.Equal(t, "text/html", w.Result().Header.Get("Content-Type")) 59 | 60 | body, err := io.ReadAll(w.Result().Body) 61 | require.NoError(t, err) 62 | require.Equal(t, "some data", string(body)) 63 | }) 64 | }) 65 | } 66 | -------------------------------------------------------------------------------- /support/gorilla/gorilla_test.go: -------------------------------------------------------------------------------- 1 | package gorilla 2 | 3 | import ( 4 | "io" 5 | "net/http" 6 | "net/http/httptest" 7 | "testing" 8 | 9 | "github.com/davidebianchi/gswagger/apirouter" 10 | "github.com/gorilla/mux" 11 | "github.com/stretchr/testify/require" 12 | ) 13 | 14 | func TestGorillaMuxRouter(t *testing.T) { 15 | muxRouter := mux.NewRouter() 16 | ar := NewRouter(muxRouter) 17 | 18 | t.Run("create a new api router", func(t *testing.T) { 19 | require.Implements(t, (*apirouter.Router[HandlerFunc, Route])(nil), ar) 20 | }) 21 | 22 | t.Run("add new route", func(t *testing.T) { 23 | route := ar.AddRoute(http.MethodGet, "/foo", func(w http.ResponseWriter, req *http.Request) { 24 | w.WriteHeader(200) 25 | w.Write(nil) 26 | }) 27 | require.IsType(t, route, &mux.Route{}) 28 | 29 | t.Run("router exposes correctly api", func(t *testing.T) { 30 | w := httptest.NewRecorder() 31 | r := httptest.NewRequest(http.MethodGet, "/foo", nil) 32 | 33 | muxRouter.ServeHTTP(w, r) 34 | 35 | require.Equal(t, http.StatusOK, w.Result().StatusCode) 36 | }) 37 | 38 | t.Run("router exposes api only to the specific method", func(t *testing.T) { 39 | w := httptest.NewRecorder() 40 | r := httptest.NewRequest(http.MethodPost, "/foo", nil) 41 | 42 | muxRouter.ServeHTTP(w, r) 43 | 44 | require.Equal(t, http.StatusMethodNotAllowed, w.Result().StatusCode) 45 | }) 46 | }) 47 | 48 | t.Run("create openapi handler", func(t *testing.T) { 49 | handlerFunc := ar.SwaggerHandler("text/html", []byte("some data")) 50 | muxRouter.HandleFunc("/oas", handlerFunc).Methods(http.MethodGet) 51 | 52 | t.Run("responds correctly to the API", func(t *testing.T) { 53 | w := httptest.NewRecorder() 54 | r := httptest.NewRequest(http.MethodGet, "/oas", nil) 55 | 56 | muxRouter.ServeHTTP(w, r) 57 | 58 | require.Equal(t, http.StatusOK, w.Result().StatusCode) 59 | require.Equal(t, "text/html", w.Result().Header.Get("Content-Type")) 60 | 61 | body, err := io.ReadAll(w.Result().Body) 62 | require.NoError(t, err) 63 | require.Equal(t, "some data", string(body)) 64 | }) 65 | }) 66 | } 67 | -------------------------------------------------------------------------------- /testdata/params-autofill.json: -------------------------------------------------------------------------------- 1 | { 2 | "info": { 3 | "title": "test openapi title", 4 | "version": "test openapi version" 5 | }, 6 | "openapi": "3.0.0", 7 | "paths": { 8 | "/cars/{carId}/drivers/{driverId}": { 9 | "get": { 10 | "parameters": [ 11 | { 12 | "in": "path", 13 | "name": "carId", 14 | "required": true, 15 | "schema": { 16 | "type": "string" 17 | } 18 | }, 19 | { 20 | "in": "path", 21 | "name": "driverId", 22 | "required": true, 23 | "schema": { 24 | "type": "string" 25 | } 26 | } 27 | ], 28 | "responses": { 29 | "default": { 30 | "description": "" 31 | } 32 | } 33 | } 34 | }, 35 | "/users/{userId}": { 36 | "get": { 37 | "parameters": [ 38 | { 39 | "in": "path", 40 | "name": "userId", 41 | "required": true, 42 | "schema": { 43 | "type": "string" 44 | } 45 | }, 46 | { 47 | "in": "query", 48 | "name": "query", 49 | "schema": { 50 | "type": "string" 51 | } 52 | } 53 | ], 54 | "responses": { 55 | "default": { 56 | "description": "" 57 | } 58 | } 59 | } 60 | }, 61 | "/files/{name}.{extension}": { 62 | "get": { 63 | "parameters": [ 64 | { 65 | "in": "path", 66 | "name": "extension", 67 | "required": true, 68 | "schema": { 69 | "type": "string" 70 | } 71 | }, 72 | { 73 | "in": "path", 74 | "name": "name", 75 | "required": true, 76 | "schema": { 77 | "type": "string" 78 | } 79 | } 80 | ], 81 | "responses": { 82 | "default": { 83 | "description": "" 84 | } 85 | } 86 | } 87 | } 88 | } 89 | } 90 | -------------------------------------------------------------------------------- /operation_test.go: -------------------------------------------------------------------------------- 1 | package swagger 2 | 3 | import ( 4 | "net/http" 5 | "testing" 6 | 7 | "github.com/getkin/kin-openapi/openapi3" 8 | "github.com/stretchr/testify/require" 9 | ) 10 | 11 | func TestNewOperation(t *testing.T) { 12 | schema := openapi3.NewObjectSchema().WithProperties(map[string]*openapi3.Schema{ 13 | "foo": openapi3.NewStringSchema(), 14 | "bar": openapi3.NewIntegerSchema().WithMax(15).WithMin(5), 15 | }) 16 | 17 | tests := []struct { 18 | name string 19 | getOperation func(t *testing.T, operation Operation) Operation 20 | expectedJSON string 21 | }{ 22 | { 23 | name: "add request body", 24 | getOperation: func(t *testing.T, operation Operation) Operation { 25 | requestBody := openapi3.NewRequestBody().WithJSONSchema(schema) 26 | operation.AddRequestBody(requestBody) 27 | operation.Responses = openapi3.NewResponses() 28 | return operation 29 | }, 30 | expectedJSON: `{"info":{"title":"test openapi title","version":"test openapi version"},"openapi":"3.0.0","paths":{"/":{"post":{"requestBody":{"content":{"application/json":{"schema":{"properties":{"bar":{"maximum":15,"minimum":5,"type":"integer"},"foo":{"type":"string"}},"type":"object"}}}},"responses":{"default":{"description":""}}}}}}`, 31 | }, 32 | { 33 | name: "add response", 34 | getOperation: func(t *testing.T, operation Operation) Operation { 35 | response := openapi3.NewResponse().WithJSONSchema(schema) 36 | operation.AddResponse(200, response) 37 | return operation 38 | }, 39 | expectedJSON: `{"info":{"title":"test openapi title","version":"test openapi version"},"openapi":"3.0.0","paths":{"/":{"post":{"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"bar":{"maximum":15,"minimum":5,"type":"integer"},"foo":{"type":"string"}},"type":"object"}}},"description":""}}}}}}`, 40 | }, 41 | } 42 | 43 | for _, test := range tests { 44 | t.Run(test.name, func(t *testing.T) { 45 | openapi := getBaseSwagger(t) 46 | openapi.OpenAPI = "3.0.0" 47 | operation := test.getOperation(t, NewOperation()) 48 | 49 | openapi.AddOperation("/", http.MethodPost, operation.Operation) 50 | 51 | data, _ := openapi.MarshalJSON() 52 | jsonData := string(data) 53 | require.JSONEq(t, test.expectedJSON, jsonData, "actual json data: %s", jsonData) 54 | }) 55 | } 56 | } 57 | -------------------------------------------------------------------------------- /testdata/allof.json: -------------------------------------------------------------------------------- 1 | { 2 | "info": { 3 | "title": "test openapi title", 4 | "version": "test openapi version" 5 | }, 6 | "openapi": "3.0.0", 7 | "paths": { 8 | "/all-of": { 9 | "post": { 10 | "requestBody": { 11 | "content": { 12 | "application/json": { 13 | "schema": { 14 | "allOf": [ 15 | { 16 | "maximum": 2, 17 | "minimum": 1, 18 | "type": "number" 19 | }, 20 | { 21 | "maximum": 3, 22 | "minimum": 2, 23 | "type": "number" 24 | } 25 | ] 26 | } 27 | } 28 | } 29 | }, 30 | "responses": { 31 | "200": { 32 | "content": { 33 | "application/json": { 34 | "schema": { 35 | "allOf": [ 36 | { 37 | "maximum": 2, 38 | "minimum": 1, 39 | "type": "number" 40 | }, 41 | { 42 | "maximum": 3, 43 | "minimum": 2, 44 | "type": "number" 45 | } 46 | ] 47 | } 48 | } 49 | }, 50 | "description": "" 51 | } 52 | } 53 | } 54 | }, 55 | "/nested-schema": { 56 | "get": { 57 | "responses": { 58 | "200": { 59 | "content": { 60 | "application/json": { 61 | "schema": { 62 | "properties": { 63 | "foo": { 64 | "type": "string" 65 | }, 66 | "nested": { 67 | "allOf": [ 68 | { 69 | "maximum": 2, 70 | "minimum": 1, 71 | "type": "number" 72 | }, 73 | { 74 | "maximum": 3, 75 | "minimum": 2, 76 | "type": "number" 77 | } 78 | ] 79 | } 80 | } 81 | } 82 | } 83 | }, 84 | "description": "" 85 | } 86 | } 87 | } 88 | } 89 | } 90 | } 91 | -------------------------------------------------------------------------------- /testdata/anyof.json: -------------------------------------------------------------------------------- 1 | { 2 | "info": { 3 | "title": "test openapi title", 4 | "version": "test openapi version" 5 | }, 6 | "openapi": "3.0.0", 7 | "paths": { 8 | "/any-of": { 9 | "post": { 10 | "requestBody": { 11 | "content": { 12 | "application/json": { 13 | "schema": { 14 | "anyOf": [ 15 | { 16 | "maximum": 2, 17 | "minimum": 1, 18 | "type": "number" 19 | }, 20 | { 21 | "maximum": 3, 22 | "minimum": 2, 23 | "type": "number" 24 | } 25 | ] 26 | } 27 | } 28 | } 29 | }, 30 | "responses": { 31 | "200": { 32 | "content": { 33 | "application/json": { 34 | "schema": { 35 | "anyOf": [ 36 | { 37 | "maximum": 2, 38 | "minimum": 1, 39 | "type": "number" 40 | }, 41 | { 42 | "maximum": 3, 43 | "minimum": 2, 44 | "type": "number" 45 | } 46 | ] 47 | } 48 | } 49 | }, 50 | "description": "" 51 | } 52 | } 53 | } 54 | }, 55 | "/nested-schema": { 56 | "get": { 57 | "responses": { 58 | "200": { 59 | "content": { 60 | "application/json": { 61 | "schema": { 62 | "properties": { 63 | "foo": { 64 | "type": "string" 65 | }, 66 | "nested": { 67 | "anyOf": [ 68 | { 69 | "maximum": 2, 70 | "minimum": 1, 71 | "type": "number" 72 | }, 73 | { 74 | "maximum": 3, 75 | "minimum": 2, 76 | "type": "number" 77 | } 78 | ] 79 | } 80 | } 81 | } 82 | } 83 | }, 84 | "description": "" 85 | } 86 | } 87 | } 88 | } 89 | } 90 | } 91 | -------------------------------------------------------------------------------- /testdata/oneOf.json: -------------------------------------------------------------------------------- 1 | { 2 | "info": { 3 | "title": "test openapi title", 4 | "version": "test openapi version" 5 | }, 6 | "openapi": "3.0.0", 7 | "paths": { 8 | "/one-of": { 9 | "post": { 10 | "requestBody": { 11 | "content": { 12 | "application/json": { 13 | "schema": { 14 | "oneOf": [ 15 | { 16 | "maximum": 2, 17 | "minimum": 1, 18 | "type": "number" 19 | }, 20 | { 21 | "maximum": 3, 22 | "minimum": 2, 23 | "type": "number" 24 | } 25 | ] 26 | } 27 | } 28 | } 29 | }, 30 | "responses": { 31 | "200": { 32 | "content": { 33 | "application/json": { 34 | "schema": { 35 | "oneOf": [ 36 | { 37 | "maximum": 2, 38 | "minimum": 1, 39 | "type": "number" 40 | }, 41 | { 42 | "maximum": 3, 43 | "minimum": 2, 44 | "type": "number" 45 | } 46 | ] 47 | } 48 | } 49 | }, 50 | "description": "" 51 | } 52 | } 53 | } 54 | }, 55 | "/user-profile": { 56 | "post": { 57 | "requestBody": { 58 | "content": { 59 | "application/json": { 60 | "schema": { 61 | "additionalProperties": false, 62 | "properties": { 63 | "firstName": { 64 | "title": "user first name", 65 | "type": "string" 66 | }, 67 | "lastName": { 68 | "title": "user last name", 69 | "type": "string" 70 | }, 71 | "metadata": { 72 | "oneOf": [ 73 | { 74 | "type": "string" 75 | }, 76 | { 77 | "type": "number" 78 | } 79 | ], 80 | "title": "custom properties" 81 | }, 82 | "userType": { 83 | "title": "type of user", 84 | "type": "string", 85 | "enum": ["simple", "advanced"] 86 | } 87 | }, 88 | "required": [ 89 | "firstName", 90 | "lastName" 91 | ], 92 | "type": "object" 93 | } 94 | } 95 | } 96 | }, 97 | "responses": { 98 | "200": { 99 | "content": { 100 | "text/plain": { 101 | "schema": { 102 | "type": "string" 103 | } 104 | } 105 | }, 106 | "description": "" 107 | } 108 | } 109 | } 110 | } 111 | } 112 | } 113 | -------------------------------------------------------------------------------- /support/gorilla/examples_test.go: -------------------------------------------------------------------------------- 1 | package gorilla_test 2 | 3 | import ( 4 | "context" 5 | "io" 6 | "net/http" 7 | "net/http/httptest" 8 | "os" 9 | "testing" 10 | 11 | swagger "github.com/davidebianchi/gswagger" 12 | "github.com/davidebianchi/gswagger/support/gorilla" 13 | "github.com/stretchr/testify/require" 14 | 15 | "github.com/getkin/kin-openapi/openapi3" 16 | "github.com/gorilla/mux" 17 | ) 18 | 19 | func TestExample(t *testing.T) { 20 | context := context.Background() 21 | muxRouter := mux.NewRouter() 22 | 23 | router, _ := swagger.NewRouter(gorilla.NewRouter(muxRouter), swagger.Options{ 24 | Context: context, 25 | Openapi: &openapi3.T{ 26 | Info: &openapi3.Info{ 27 | Title: "my title", 28 | Version: "1.0.0", 29 | }, 30 | }, 31 | }) 32 | 33 | okHandler := func(w http.ResponseWriter, req *http.Request) { 34 | w.WriteHeader(http.StatusOK) 35 | w.Write([]byte("OK")) 36 | } 37 | 38 | type User struct { 39 | Name string `json:"name" jsonschema:"title=The user name,required" jsonschema_extras:"example=Jane"` 40 | PhoneNumber int `json:"phone" jsonschema:"title=mobile number of user"` 41 | Groups []string `json:"groups,omitempty" jsonschema:"title=groups of the user,default=users"` 42 | Address string `json:"address" jsonschema:"title=user address"` 43 | } 44 | type errorResponse struct { 45 | Message string `json:"message"` 46 | } 47 | 48 | router.AddRoute(http.MethodPost, "/users", okHandler, swagger.Definitions{ 49 | RequestBody: &swagger.ContentValue{ 50 | Content: swagger.Content{ 51 | "application/json": {Value: User{}}, 52 | }, 53 | }, 54 | Responses: map[int]swagger.ContentValue{ 55 | 201: { 56 | Content: swagger.Content{ 57 | "text/html": {Value: ""}, 58 | }, 59 | }, 60 | 401: { 61 | Content: swagger.Content{ 62 | "application/json": {Value: &errorResponse{}}, 63 | }, 64 | Description: "invalid request", 65 | }, 66 | }, 67 | }) 68 | 69 | router.AddRoute(http.MethodGet, "/users", okHandler, swagger.Definitions{ 70 | Responses: map[int]swagger.ContentValue{ 71 | 200: { 72 | Content: swagger.Content{ 73 | "application/json": {Value: &[]User{}}, 74 | }, 75 | }, 76 | }, 77 | }) 78 | 79 | carSchema := openapi3.NewObjectSchema().WithProperties(map[string]*openapi3.Schema{ 80 | "foo": openapi3.NewStringSchema(), 81 | "bar": openapi3.NewIntegerSchema().WithMax(15).WithMin(5), 82 | }) 83 | requestBody := openapi3.NewRequestBody().WithJSONSchema(carSchema) 84 | operation := swagger.NewOperation() 85 | operation.AddRequestBody(requestBody) 86 | 87 | router.AddRawRoute(http.MethodPost, "/cars", okHandler, operation) 88 | 89 | _, err := router.AddRoute(http.MethodGet, "/users/{userId}", okHandler, swagger.Definitions{ 90 | Querystring: swagger.ParameterValue{ 91 | "query": { 92 | Schema: &swagger.Schema{Value: ""}, 93 | }, 94 | }, 95 | }) 96 | require.NoError(t, err) 97 | 98 | _, err = router.AddRoute(http.MethodGet, "/cars/{carId}/drivers/{driverId}", okHandler, swagger.Definitions{}) 99 | require.NoError(t, err) 100 | 101 | router.GenerateAndExposeOpenapi() 102 | 103 | t.Run("correctly exposes documentation", func(t *testing.T) { 104 | w := httptest.NewRecorder() 105 | req := httptest.NewRequest(http.MethodGet, swagger.DefaultJSONDocumentationPath, nil) 106 | 107 | muxRouter.ServeHTTP(w, req) 108 | 109 | require.Equal(t, http.StatusOK, w.Result().StatusCode) 110 | require.Equal(t, "application/json", w.Result().Header.Get("Content-Type")) 111 | 112 | body, err := io.ReadAll(w.Result().Body) 113 | require.NoError(t, err) 114 | expected, err := os.ReadFile("./testdata/examples-users.json") 115 | require.NoError(t, err) 116 | require.JSONEq(t, string(expected), string(body), "actual json data: %s", body) 117 | }) 118 | } 119 | -------------------------------------------------------------------------------- /testdata/users_employees.yaml: -------------------------------------------------------------------------------- 1 | info: 2 | title: test openapi title 3 | version: test openapi version 4 | openapi: 3.0.0 5 | paths: 6 | /employees: 7 | get: 8 | responses: 9 | '200': 10 | content: 11 | application/json: 12 | schema: 13 | additionalProperties: false 14 | properties: 15 | organization_name: 16 | type: string 17 | users: 18 | items: 19 | additionalProperties: false 20 | properties: 21 | address: 22 | title: user address 23 | type: string 24 | groups: 25 | default: 26 | - users 27 | items: 28 | type: string 29 | title: groups of the user 30 | type: array 31 | name: 32 | example: Jane 33 | title: The user name 34 | type: string 35 | phone: 36 | title: mobile number of user 37 | type: integer 38 | required: 39 | - name 40 | - phone 41 | - address 42 | type: object 43 | type: array 44 | required: 45 | - organization_name 46 | - users 47 | type: object 48 | description: '' 49 | /users: 50 | get: 51 | responses: 52 | '200': 53 | content: 54 | application/json: 55 | schema: 56 | items: 57 | additionalProperties: false 58 | properties: 59 | address: 60 | title: user address 61 | type: string 62 | groups: 63 | default: 64 | - users 65 | items: 66 | type: string 67 | title: groups of the user 68 | type: array 69 | name: 70 | example: Jane 71 | title: The user name 72 | type: string 73 | phone: 74 | title: mobile number of user 75 | type: integer 76 | required: 77 | - name 78 | - phone 79 | - address 80 | type: object 81 | type: array 82 | description: '' 83 | post: 84 | requestBody: 85 | content: 86 | application/json: 87 | schema: 88 | additionalProperties: false 89 | properties: 90 | address: 91 | title: user address 92 | type: string 93 | groups: 94 | default: 95 | - users 96 | items: 97 | type: string 98 | title: groups of the user 99 | type: array 100 | name: 101 | example: Jane 102 | title: The user name 103 | type: string 104 | phone: 105 | title: mobile number of user 106 | type: integer 107 | required: 108 | - name 109 | - phone 110 | - address 111 | type: object 112 | responses: 113 | '201': 114 | content: 115 | text/html: 116 | schema: 117 | type: string 118 | description: '' 119 | '401': 120 | content: 121 | application/json: 122 | schema: 123 | additionalProperties: false 124 | properties: 125 | message: 126 | type: string 127 | required: 128 | - message 129 | type: object 130 | description: invalid request 131 | -------------------------------------------------------------------------------- /CHANGELOG.md: -------------------------------------------------------------------------------- 1 | # Changelog 2 | 3 | All notable changes to this project will be documented in this file. 4 | 5 | The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), 6 | and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). 7 | 8 | ## Unreleased 9 | 10 | ## 0.10.1 - 06-10-2025 11 | 12 | ### Refactor 13 | 14 | - renamed swagger to openapi in error messages 15 | 16 | ## 0.10.0 - 28-02-2024 17 | 18 | ### BREAKING CHANGES 19 | 20 | - remove support to golang 1.19 21 | 22 | ### Updated 23 | 24 | - change jsonschema lib to use again `invopop/jsonschema` one, since now it support additionalProperties instead of patternProperties 25 | 26 | ## 0.9.0 - 17-04-2023 27 | 28 | ### Added 29 | 30 | - add new fields to Definition: 31 | - Security 32 | - Tags 33 | - Summary 34 | - Description 35 | - Deprecated 36 | - Extensions 37 | 38 | ### Updated 39 | 40 | - update kin-openapi to 0.114.0: this change removes components from exposed oas (if not manually set). In this update of kin-openapi, there is a breaking change with the T struct, which now accepts component as pointer. 41 | 42 | ## 0.8.0 - 23-12-2022 43 | 44 | ### BREAKING CHANGES 45 | 46 | - add `TransformPathToOasPath(path string) string` method to apirouter.Router interface to handle different types of paths parameters. If you use one of the supported routers, you should do nothing; 47 | 48 | ## 0.7.0 - 22-12-2022 49 | 50 | This is a big major release. The main achievement is to increase the usability of this library to all the routers. 51 | Below are listed the breaking changes you should care when update the version. 52 | 53 | ### BREAKING CHANGES 54 | 55 | - `apirouter.NewGorillaMuxRouter` is now `gorilla.NewRouter` (exposed by package `github.com/davidebianchi/gswagger/support/gorilla`). 56 | - removed `apirouter.HandlerFunc`. Now it is exposed by `gorilla.HandlerFunc` 57 | - changed `apirouter.Router` interface: 58 | - now it accept a generics `HandlerFunc` to define the handler function 59 | - add method `SwaggerHandler(contentType string, json []byte) HandlerFunc` 60 | - `NewRouter` function now accept `HandlerFunc` as generics 61 | - drop support to golang <= 1.17 62 | - `GenerateAndExposeSwagger` renamed to `GenerateAndExposeOpenapi` 63 | 64 | ### Feature 65 | 66 | - support to different types of routers 67 | - add [fiber](https://github.com/gofiber/fiber) support 68 | - add [echo](https://echo.labstack.com/) support 69 | 70 | ## 0.6.1 - 17-11-2022 71 | 72 | ### Changed 73 | 74 | - change jsonschema lib to `mia-platform/jsonschema v0.1.0`. This update removes the `patternProperties` with `additionalProperties` from all schemas 75 | - remove use of deprecated io/ioutil lib 76 | 77 | ## 0.6.0 - 04-11-2022 78 | 79 | ### Added 80 | 81 | - Tags support to `router.AddRoute` accepted definition 82 | 83 | ## 0.5.1 - 03-10-2022 84 | 85 | ### Fixed 86 | 87 | - upgrade deps 88 | 89 | ## v0.5.0 - 05-08-2022 90 | 91 | ### Added 92 | 93 | - path params are auto generated if not set 94 | 95 | ## v0.4.0 - 02-08-2022 96 | 97 | ### Changed 98 | 99 | - change jsonschema lib to `invopop/jsonschema v0.5.0`. This updates remove the `additionalProperties: true` from all the schemas, as it is the default value 100 | 101 | ### BREAKING CHANGES 102 | 103 | - modified Router interface by sorting addRoute arguments in a different manner: first method and then path 104 | To migrate, all the router implementation must be updated with the Router interface change. 105 | 106 | Before: 107 | 108 | ```go 109 | type Router interface { 110 | AddRoute(path, method string, handler HandlerFunc) Route 111 | } 112 | ``` 113 | 114 | After: 115 | 116 | ```go 117 | type Router interface { 118 | AddRoute(method, path string, handler HandlerFunc) Route 119 | } 120 | ``` 121 | 122 | ### Updates 123 | 124 | - kin-openapi@v0.98.0 125 | - go-openapi/swag@v0.21.1 126 | - labstack/echo/v4@v4.7.2 127 | 128 | ## v0.3.0 - 10-11-2021 129 | 130 | ### Added 131 | 132 | - handle router with path prefix 133 | - add SubRouter method to use a new sub router 134 | 135 | ## v0.2.0 - 16-10-2021 136 | 137 | ### BREAKING CHANGES 138 | 139 | Introduced the `apirouter.Router` interface, which abstract the used router. 140 | Changed function are: 141 | 142 | - Router struct now support `apirouter.Router` interface 143 | - NewRouter function accepted router is an `apirouter.Router` 144 | - AddRawRoute now accept `apirouter.Handler` iterface 145 | - AddRawRoute returns an interface instead of *mux.Router. This interface is the Route returned by specific Router 146 | - AddRoute now accept `apirouter.Handler` iterface 147 | - AddRoute returns an interface instead of *mux.Router. This interface is the Route returned by specific Router 148 | 149 | ## v0.1.0 150 | 151 | Initial release 152 | -------------------------------------------------------------------------------- /support/gorilla/integration_test.go: -------------------------------------------------------------------------------- 1 | package gorilla_test 2 | 3 | import ( 4 | "context" 5 | "io" 6 | "net/http" 7 | "net/http/httptest" 8 | "os" 9 | "testing" 10 | 11 | swagger "github.com/davidebianchi/gswagger" 12 | "github.com/davidebianchi/gswagger/support/gorilla" 13 | "github.com/getkin/kin-openapi/openapi3" 14 | "github.com/gorilla/mux" 15 | "github.com/stretchr/testify/require" 16 | ) 17 | 18 | const ( 19 | swaggerOpenapiTitle = "test openapi title" 20 | swaggerOpenapiVersion = "test openapi version" 21 | ) 22 | 23 | type SwaggerRouter = swagger.Router[gorilla.HandlerFunc, gorilla.Route] 24 | 25 | func TestGorillaIntegration(t *testing.T) { 26 | t.Run("router works correctly", func(t *testing.T) { 27 | muxRouter, oasRouter := setupSwagger(t) 28 | 29 | err := oasRouter.GenerateAndExposeOpenapi() 30 | require.NoError(t, err) 31 | 32 | w := httptest.NewRecorder() 33 | r := httptest.NewRequest(http.MethodGet, "/hello", nil) 34 | 35 | muxRouter.ServeHTTP(w, r) 36 | 37 | require.Equal(t, http.StatusOK, w.Result().StatusCode) 38 | 39 | body := readBody(t, w.Result().Body) 40 | require.Equal(t, "OK", body) 41 | 42 | t.Run("and generate swagger", func(t *testing.T) { 43 | w := httptest.NewRecorder() 44 | r := httptest.NewRequest(http.MethodGet, swagger.DefaultJSONDocumentationPath, nil) 45 | 46 | muxRouter.ServeHTTP(w, r) 47 | 48 | require.Equal(t, http.StatusOK, w.Result().StatusCode) 49 | 50 | body := readBody(t, w.Result().Body) 51 | require.JSONEq(t, readFile(t, "../testdata/integration.json"), body) 52 | }) 53 | }) 54 | 55 | t.Run("works correctly with subrouter - handles path prefix - gorilla mux", func(t *testing.T) { 56 | muxRouter, oasRouter := setupSwagger(t) 57 | 58 | muxSubRouter := muxRouter.NewRoute().Subrouter() 59 | subRouter, err := oasRouter.SubRouter(gorilla.NewRouter(muxSubRouter), swagger.SubRouterOptions{ 60 | PathPrefix: "/prefix", 61 | }) 62 | require.NoError(t, err) 63 | 64 | _, err = subRouter.AddRoute(http.MethodGet, "/foo", okHandler, swagger.Definitions{}) 65 | require.NoError(t, err) 66 | 67 | err = oasRouter.GenerateAndExposeOpenapi() 68 | require.NoError(t, err) 69 | 70 | t.Run("correctly call router", func(t *testing.T) { 71 | w := httptest.NewRecorder() 72 | r := httptest.NewRequest(http.MethodGet, "/hello", nil) 73 | 74 | muxRouter.ServeHTTP(w, r) 75 | 76 | require.Equal(t, http.StatusOK, w.Result().StatusCode) 77 | 78 | body := readBody(t, w.Result().Body) 79 | require.Equal(t, "OK", body) 80 | }) 81 | 82 | t.Run("correctly call sub router", func(t *testing.T) { 83 | w := httptest.NewRecorder() 84 | r := httptest.NewRequest(http.MethodGet, "/prefix/foo", nil) 85 | 86 | muxRouter.ServeHTTP(w, r) 87 | 88 | require.Equal(t, http.StatusOK, w.Result().StatusCode) 89 | 90 | body := readBody(t, w.Result().Body) 91 | require.Equal(t, "OK", body) 92 | }) 93 | 94 | t.Run("and generate swagger", func(t *testing.T) { 95 | w := httptest.NewRecorder() 96 | r := httptest.NewRequest(http.MethodGet, swagger.DefaultJSONDocumentationPath, nil) 97 | 98 | muxRouter.ServeHTTP(w, r) 99 | 100 | require.Equal(t, http.StatusOK, w.Result().StatusCode) 101 | 102 | body := readBody(t, w.Result().Body) 103 | require.JSONEq(t, readFile(t, "../testdata/intergation-subrouter.json"), body, body) 104 | }) 105 | }) 106 | } 107 | 108 | func readBody(t *testing.T, requestBody io.ReadCloser) string { 109 | t.Helper() 110 | 111 | body, err := io.ReadAll(requestBody) 112 | require.NoError(t, err) 113 | 114 | return string(body) 115 | } 116 | 117 | func setupSwagger(t *testing.T) (*mux.Router, *SwaggerRouter) { 118 | t.Helper() 119 | 120 | context := context.Background() 121 | muxRouter := mux.NewRouter() 122 | 123 | router, err := swagger.NewRouter(gorilla.NewRouter(muxRouter), swagger.Options{ 124 | Context: context, 125 | Openapi: &openapi3.T{ 126 | Info: &openapi3.Info{ 127 | Title: swaggerOpenapiTitle, 128 | Version: swaggerOpenapiVersion, 129 | }, 130 | }, 131 | }) 132 | require.NoError(t, err) 133 | 134 | operation := swagger.Operation{} 135 | 136 | _, err = router.AddRawRoute(http.MethodGet, "/hello", okHandler, operation) 137 | require.NoError(t, err) 138 | 139 | _, err = router.AddRoute(http.MethodPost, "/hello/{value}", okHandler, swagger.Definitions{}) 140 | require.NoError(t, err) 141 | 142 | return muxRouter, router 143 | } 144 | 145 | func okHandler(w http.ResponseWriter, req *http.Request) { 146 | w.WriteHeader(http.StatusOK) 147 | w.Write([]byte(`OK`)) 148 | } 149 | 150 | func readFile(t *testing.T, path string) string { 151 | t.Helper() 152 | 153 | fileContent, err := os.ReadFile(path) 154 | require.NoError(t, err) 155 | 156 | return string(fileContent) 157 | } 158 | -------------------------------------------------------------------------------- /support/fiber/integration_test.go: -------------------------------------------------------------------------------- 1 | package fiber_test 2 | 3 | import ( 4 | "context" 5 | "io" 6 | "net/http" 7 | "net/http/httptest" 8 | "os" 9 | "testing" 10 | 11 | swagger "github.com/davidebianchi/gswagger" 12 | oasFiber "github.com/davidebianchi/gswagger/support/fiber" 13 | 14 | "github.com/getkin/kin-openapi/openapi3" 15 | "github.com/gofiber/fiber/v2" 16 | "github.com/stretchr/testify/require" 17 | ) 18 | 19 | type SwaggerRouter = swagger.Router[oasFiber.HandlerFunc, oasFiber.Route] 20 | 21 | const ( 22 | swaggerOpenapiTitle = "test openapi title" 23 | swaggerOpenapiVersion = "test openapi version" 24 | ) 25 | 26 | func TestFiberIntegration(t *testing.T) { 27 | t.Run("router works correctly", func(t *testing.T) { 28 | router, oasRouter := setupSwagger(t) 29 | 30 | err := oasRouter.GenerateAndExposeOpenapi() 31 | require.NoError(t, err) 32 | 33 | t.Run("/hello", func(t *testing.T) { 34 | r := httptest.NewRequest(http.MethodGet, "/hello", nil) 35 | 36 | resp, err := router.Test(r) 37 | require.NoError(t, err) 38 | require.Equal(t, http.StatusOK, resp.StatusCode) 39 | 40 | body := readBody(t, resp.Body) 41 | require.Equal(t, "OK", body) 42 | }) 43 | 44 | t.Run("/hello/:value", func(t *testing.T) { 45 | r := httptest.NewRequest(http.MethodPost, "/hello/something", nil) 46 | 47 | resp, err := router.Test(r) 48 | require.NoError(t, err) 49 | require.Equal(t, http.StatusOK, resp.StatusCode) 50 | 51 | body := readBody(t, resp.Body) 52 | require.Equal(t, "OK", body) 53 | }) 54 | 55 | t.Run("and generate swagger", func(t *testing.T) { 56 | r := httptest.NewRequest(http.MethodGet, swagger.DefaultJSONDocumentationPath, nil) 57 | 58 | resp, err := router.Test(r) 59 | require.NoError(t, err) 60 | require.Equal(t, http.StatusOK, resp.StatusCode) 61 | 62 | body := readBody(t, resp.Body) 63 | require.JSONEq(t, readFile(t, "../testdata/integration.json"), body, body) 64 | }) 65 | }) 66 | 67 | t.Run("works correctly with subrouter - handles path prefix - gorilla mux", func(t *testing.T) { 68 | fiberRouter, oasRouter := setupSwagger(t) 69 | 70 | subRouter, err := oasRouter.SubRouter(oasFiber.NewRouter(fiberRouter), swagger.SubRouterOptions{ 71 | PathPrefix: "/prefix", 72 | }) 73 | require.NoError(t, err) 74 | 75 | _, err = subRouter.AddRoute(http.MethodGet, "/foo", okHandler, swagger.Definitions{}) 76 | require.NoError(t, err) 77 | 78 | err = oasRouter.GenerateAndExposeOpenapi() 79 | require.NoError(t, err) 80 | 81 | t.Run("correctly call /hello", func(t *testing.T) { 82 | r := httptest.NewRequest(http.MethodGet, "/hello", nil) 83 | 84 | resp, err := fiberRouter.Test(r) 85 | require.NoError(t, err) 86 | require.Equal(t, http.StatusOK, resp.StatusCode) 87 | 88 | body := readBody(t, resp.Body) 89 | require.Equal(t, "OK", body) 90 | }) 91 | 92 | t.Run("correctly call sub router", func(t *testing.T) { 93 | r := httptest.NewRequest(http.MethodGet, "/prefix/foo", nil) 94 | 95 | resp, err := fiberRouter.Test(r) 96 | require.NoError(t, err) 97 | require.Equal(t, http.StatusOK, resp.StatusCode) 98 | 99 | body := readBody(t, resp.Body) 100 | require.Equal(t, "OK", body) 101 | }) 102 | 103 | t.Run("and generate swagger", func(t *testing.T) { 104 | r := httptest.NewRequest(http.MethodGet, swagger.DefaultJSONDocumentationPath, nil) 105 | 106 | resp, err := fiberRouter.Test(r) 107 | require.NoError(t, err) 108 | require.Equal(t, http.StatusOK, resp.StatusCode) 109 | 110 | body := readBody(t, resp.Body) 111 | require.JSONEq(t, readFile(t, "../testdata/intergation-subrouter.json"), body, body) 112 | }) 113 | }) 114 | } 115 | 116 | func setupSwagger(t *testing.T) (*fiber.App, *SwaggerRouter) { 117 | t.Helper() 118 | 119 | context := context.Background() 120 | fiberRouter := fiber.New() 121 | 122 | router, err := swagger.NewRouter(oasFiber.NewRouter(fiberRouter), swagger.Options{ 123 | Context: context, 124 | Openapi: &openapi3.T{ 125 | Info: &openapi3.Info{ 126 | Title: swaggerOpenapiTitle, 127 | Version: swaggerOpenapiVersion, 128 | }, 129 | }, 130 | }) 131 | require.NoError(t, err) 132 | 133 | operation := swagger.Operation{} 134 | 135 | _, err = router.AddRawRoute(http.MethodGet, "/hello", okHandler, operation) 136 | require.NoError(t, err) 137 | 138 | _, err = router.AddRoute(http.MethodPost, "/hello/:value", okHandler, swagger.Definitions{}) 139 | require.NoError(t, err) 140 | 141 | return fiberRouter, router 142 | } 143 | 144 | func okHandler(c *fiber.Ctx) error { 145 | c.Status(http.StatusOK) 146 | return c.SendString("OK") 147 | } 148 | 149 | func readBody(t *testing.T, requestBody io.ReadCloser) string { 150 | t.Helper() 151 | 152 | body, err := io.ReadAll(requestBody) 153 | require.NoError(t, err) 154 | 155 | return string(body) 156 | } 157 | 158 | func readFile(t *testing.T, path string) string { 159 | t.Helper() 160 | 161 | fileContent, err := os.ReadFile(path) 162 | require.NoError(t, err) 163 | 164 | return string(fileContent) 165 | } 166 | -------------------------------------------------------------------------------- /support/echo/integration_test.go: -------------------------------------------------------------------------------- 1 | package echo_test 2 | 3 | import ( 4 | "context" 5 | "io" 6 | "net/http" 7 | "net/http/httptest" 8 | "os" 9 | "testing" 10 | 11 | oasEcho "github.com/davidebianchi/gswagger/support/echo" 12 | 13 | swagger "github.com/davidebianchi/gswagger" 14 | "github.com/getkin/kin-openapi/openapi3" 15 | "github.com/labstack/echo/v4" 16 | "github.com/stretchr/testify/require" 17 | ) 18 | 19 | const ( 20 | swaggerOpenapiTitle = "test openapi title" 21 | swaggerOpenapiVersion = "test openapi version" 22 | ) 23 | 24 | type echoSwaggerRouter = swagger.Router[echo.HandlerFunc, *echo.Route] 25 | 26 | func TestEchoIntegration(t *testing.T) { 27 | t.Run("router works correctly - echo", func(t *testing.T) { 28 | echoRouter, oasRouter := setupEchoSwagger(t) 29 | 30 | err := oasRouter.GenerateAndExposeOpenapi() 31 | require.NoError(t, err) 32 | 33 | t.Run("/hello", func(t *testing.T) { 34 | w := httptest.NewRecorder() 35 | r := httptest.NewRequest(http.MethodGet, "/hello", nil) 36 | 37 | echoRouter.ServeHTTP(w, r) 38 | 39 | require.Equal(t, http.StatusOK, w.Result().StatusCode) 40 | 41 | body := readBody(t, w.Result().Body) 42 | require.Equal(t, "OK", body) 43 | }) 44 | 45 | t.Run("/hello/:value", func(t *testing.T) { 46 | w := httptest.NewRecorder() 47 | r := httptest.NewRequest(http.MethodPost, "/hello/something", nil) 48 | 49 | echoRouter.ServeHTTP(w, r) 50 | 51 | require.Equal(t, http.StatusOK, w.Result().StatusCode) 52 | 53 | body := readBody(t, w.Result().Body) 54 | require.Equal(t, "OK", body) 55 | }) 56 | 57 | t.Run("and generate swagger", func(t *testing.T) { 58 | w := httptest.NewRecorder() 59 | r := httptest.NewRequest(http.MethodGet, swagger.DefaultJSONDocumentationPath, nil) 60 | 61 | echoRouter.ServeHTTP(w, r) 62 | 63 | require.Equal(t, http.StatusOK, w.Result().StatusCode) 64 | 65 | body := readBody(t, w.Result().Body) 66 | require.JSONEq(t, readFile(t, "../testdata/integration.json"), body) 67 | }) 68 | }) 69 | 70 | t.Run("works correctly with subrouter - handles path prefix - echo", func(t *testing.T) { 71 | eRouter, oasRouter := setupEchoSwagger(t) 72 | 73 | subRouter, err := oasRouter.SubRouter(oasEcho.NewRouter(eRouter), swagger.SubRouterOptions{ 74 | PathPrefix: "/prefix", 75 | }) 76 | require.NoError(t, err) 77 | 78 | _, err = subRouter.AddRoute(http.MethodGet, "/foo", okHandler, swagger.Definitions{}) 79 | require.NoError(t, err) 80 | 81 | err = oasRouter.GenerateAndExposeOpenapi() 82 | require.NoError(t, err) 83 | 84 | t.Run("correctly call /hello", func(t *testing.T) { 85 | w := httptest.NewRecorder() 86 | r := httptest.NewRequest(http.MethodGet, "/hello", nil) 87 | 88 | eRouter.ServeHTTP(w, r) 89 | 90 | require.Equal(t, http.StatusOK, w.Result().StatusCode) 91 | 92 | body := readBody(t, w.Result().Body) 93 | require.Equal(t, "OK", body) 94 | }) 95 | 96 | t.Run("correctly call sub router", func(t *testing.T) { 97 | w := httptest.NewRecorder() 98 | r := httptest.NewRequest(http.MethodGet, "/prefix/foo", nil) 99 | 100 | eRouter.ServeHTTP(w, r) 101 | 102 | require.Equal(t, http.StatusOK, w.Result().StatusCode) 103 | 104 | body := readBody(t, w.Result().Body) 105 | require.Equal(t, "OK", body) 106 | }) 107 | 108 | t.Run("and generate swagger", func(t *testing.T) { 109 | w := httptest.NewRecorder() 110 | r := httptest.NewRequest(http.MethodGet, swagger.DefaultJSONDocumentationPath, nil) 111 | 112 | eRouter.ServeHTTP(w, r) 113 | 114 | require.Equal(t, http.StatusOK, w.Result().StatusCode) 115 | 116 | body := readBody(t, w.Result().Body) 117 | require.JSONEq(t, readFile(t, "../testdata/intergation-subrouter.json"), body, body) 118 | }) 119 | }) 120 | } 121 | 122 | func readBody(t *testing.T, requestBody io.ReadCloser) string { 123 | t.Helper() 124 | 125 | body, err := io.ReadAll(requestBody) 126 | require.NoError(t, err) 127 | 128 | return string(body) 129 | } 130 | 131 | func setupEchoSwagger(t *testing.T) (*echo.Echo, *echoSwaggerRouter) { 132 | t.Helper() 133 | 134 | context := context.Background() 135 | e := echo.New() 136 | 137 | router, err := swagger.NewRouter(oasEcho.NewRouter(e), swagger.Options{ 138 | Context: context, 139 | Openapi: &openapi3.T{ 140 | Info: &openapi3.Info{ 141 | Title: swaggerOpenapiTitle, 142 | Version: swaggerOpenapiVersion, 143 | }, 144 | }, 145 | }) 146 | require.NoError(t, err) 147 | 148 | operation := swagger.Operation{} 149 | 150 | _, err = router.AddRawRoute(http.MethodGet, "/hello", okHandler, operation) 151 | require.NoError(t, err) 152 | 153 | _, err = router.AddRoute(http.MethodPost, "/hello/:value", okHandler, swagger.Definitions{}) 154 | require.NoError(t, err) 155 | 156 | return e, router 157 | } 158 | 159 | func okHandler(c echo.Context) error { 160 | return c.String(http.StatusOK, "OK") 161 | } 162 | 163 | func readFile(t *testing.T, path string) string { 164 | t.Helper() 165 | 166 | fileContent, err := os.ReadFile(path) 167 | require.NoError(t, err) 168 | 169 | return string(fileContent) 170 | } 171 | -------------------------------------------------------------------------------- /support/gorilla/testdata/examples-users.json: -------------------------------------------------------------------------------- 1 | { 2 | "info": { 3 | "title": "my title", 4 | "version": "1.0.0" 5 | }, 6 | "openapi": "3.0.0", 7 | "paths": { 8 | "/cars/{carId}/drivers/{driverId}": { 9 | "get": { 10 | "parameters": [ 11 | { 12 | "in": "path", 13 | "name": "carId", 14 | "required": true, 15 | "schema": { 16 | "type": "string" 17 | } 18 | }, 19 | { 20 | "in": "path", 21 | "name": "driverId", 22 | "required": true, 23 | "schema": { 24 | "type": "string" 25 | } 26 | } 27 | ], 28 | "responses": { 29 | "default": { 30 | "description": "" 31 | } 32 | } 33 | } 34 | }, 35 | "/users": { 36 | "get": { 37 | "responses": { 38 | "200": { 39 | "content": { 40 | "application/json": { 41 | "schema": { 42 | "items": { 43 | "additionalProperties": false, 44 | "properties": { 45 | "address": { 46 | "title": "user address", 47 | "type": "string" 48 | }, 49 | "groups": { 50 | "default": [ 51 | "users" 52 | ], 53 | "items": { 54 | "type": "string" 55 | }, 56 | "title": "groups of the user", 57 | "type": "array" 58 | }, 59 | "name": { 60 | "example": "Jane", 61 | "title": "The user name", 62 | "type": "string" 63 | }, 64 | "phone": { 65 | "title": "mobile number of user", 66 | "type": "integer" 67 | } 68 | }, 69 | "required": [ 70 | "name", 71 | "phone", 72 | "address" 73 | ], 74 | "type": "object" 75 | }, 76 | "type": "array" 77 | } 78 | } 79 | }, 80 | "description": "" 81 | } 82 | } 83 | }, 84 | "post": { 85 | "requestBody": { 86 | "content": { 87 | "application/json": { 88 | "schema": { 89 | "additionalProperties": false, 90 | "properties": { 91 | "address": { 92 | "title": "user address", 93 | "type": "string" 94 | }, 95 | "groups": { 96 | "default": [ 97 | "users" 98 | ], 99 | "items": { 100 | "type": "string" 101 | }, 102 | "title": "groups of the user", 103 | "type": "array" 104 | }, 105 | "name": { 106 | "example": "Jane", 107 | "title": "The user name", 108 | "type": "string" 109 | }, 110 | "phone": { 111 | "title": "mobile number of user", 112 | "type": "integer" 113 | } 114 | }, 115 | "required": [ 116 | "name", 117 | "phone", 118 | "address" 119 | ], 120 | "type": "object" 121 | } 122 | } 123 | } 124 | }, 125 | "responses": { 126 | "201": { 127 | "content": { 128 | "text/html": { 129 | "schema": { 130 | "type": "string" 131 | } 132 | } 133 | }, 134 | "description": "" 135 | }, 136 | "401": { 137 | "content": { 138 | "application/json": { 139 | "schema": { 140 | "additionalProperties": false, 141 | "properties": { 142 | "message": { 143 | "type": "string" 144 | } 145 | }, 146 | "required": [ 147 | "message" 148 | ], 149 | "type": "object" 150 | } 151 | } 152 | }, 153 | "description": "invalid request" 154 | } 155 | } 156 | } 157 | }, 158 | "/users/{userId}": { 159 | "get": { 160 | "parameters": [ 161 | { 162 | "in": "path", 163 | "name": "userId", 164 | "required": true, 165 | "schema": { 166 | "type": "string" 167 | } 168 | }, 169 | { 170 | "in": "query", 171 | "name": "query", 172 | "schema": { 173 | "type": "string" 174 | } 175 | } 176 | ], 177 | "responses": { 178 | "default": { 179 | "description": "" 180 | } 181 | } 182 | } 183 | } 184 | } 185 | } 186 | -------------------------------------------------------------------------------- /main.go: -------------------------------------------------------------------------------- 1 | package swagger 2 | 3 | import ( 4 | "context" 5 | "errors" 6 | "fmt" 7 | "net/http" 8 | "strings" 9 | 10 | "github.com/davidebianchi/gswagger/apirouter" 11 | "github.com/getkin/kin-openapi/openapi3" 12 | "github.com/ghodss/yaml" 13 | ) 14 | 15 | var ( 16 | // ErrGenerateOAS throws when fails the marshalling of the swagger struct. 17 | ErrGenerateOAS = errors.New("fail to generate openapi") 18 | // ErrValidatingOAS throws when given openapi params are not correct. 19 | ErrValidatingOAS = errors.New("fails to validate openapi") 20 | 21 | // Deprecated: ErrGenerateSwagger has been deprecated, use ErrGenerateOAS instead. 22 | ErrGenerateSwagger = ErrGenerateOAS 23 | // Deprecated: ErrValidatingSwagger has been deprecated, use ErrValidatingOAS instead. 24 | ErrValidatingSwagger = ErrValidatingOAS 25 | ) 26 | 27 | const ( 28 | // DefaultJSONDocumentationPath is the path of the openapi documentation in json format. 29 | DefaultJSONDocumentationPath = "/documentation/json" 30 | // DefaultYAMLDocumentationPath is the path of the openapi documentation in yaml format. 31 | DefaultYAMLDocumentationPath = "/documentation/yaml" 32 | defaultOpenapiVersion = "3.0.0" 33 | ) 34 | 35 | // Router handle the api router and the openapi schema. 36 | // api router supported out of the box are: 37 | // - gorilla mux 38 | type Router[HandlerFunc, Route any] struct { 39 | router apirouter.Router[HandlerFunc, Route] 40 | swaggerSchema *openapi3.T 41 | context context.Context 42 | jsonDocumentationPath string 43 | yamlDocumentationPath string 44 | pathPrefix string 45 | } 46 | 47 | // Options to be passed to create the new router and swagger 48 | type Options struct { 49 | Context context.Context 50 | Openapi *openapi3.T 51 | // JSONDocumentationPath is the path exposed by json endpoint. Default to /documentation/json. 52 | JSONDocumentationPath string 53 | // YAMLDocumentationPath is the path exposed by yaml endpoint. Default to /documentation/yaml. 54 | YAMLDocumentationPath string 55 | // Add path prefix to add to every router path. 56 | PathPrefix string 57 | } 58 | 59 | // NewRouter generate new router with openapi. Default to OpenAPI 3.0.0 60 | func NewRouter[HandlerFunc, Route any](router apirouter.Router[HandlerFunc, Route], options Options) (*Router[HandlerFunc, Route], error) { 61 | openapi, err := generateNewValidOpenapi(options.Openapi) 62 | if err != nil { 63 | return nil, fmt.Errorf("%w: %s", ErrValidatingOAS, err) 64 | } 65 | 66 | var ctx = options.Context 67 | if options.Context == nil { 68 | ctx = context.Background() 69 | } 70 | 71 | yamlDocumentationPath := DefaultYAMLDocumentationPath 72 | if options.YAMLDocumentationPath != "" { 73 | if err := isValidDocumentationPath(options.YAMLDocumentationPath); err != nil { 74 | return nil, err 75 | } 76 | yamlDocumentationPath = options.YAMLDocumentationPath 77 | } 78 | 79 | jsonDocumentationPath := DefaultJSONDocumentationPath 80 | if options.JSONDocumentationPath != "" { 81 | if err := isValidDocumentationPath(options.JSONDocumentationPath); err != nil { 82 | return nil, err 83 | } 84 | jsonDocumentationPath = options.JSONDocumentationPath 85 | } 86 | 87 | return &Router[HandlerFunc, Route]{ 88 | router: router, 89 | swaggerSchema: openapi, 90 | context: ctx, 91 | yamlDocumentationPath: yamlDocumentationPath, 92 | jsonDocumentationPath: jsonDocumentationPath, 93 | pathPrefix: options.PathPrefix, 94 | }, nil 95 | } 96 | 97 | type SubRouterOptions struct { 98 | PathPrefix string 99 | } 100 | 101 | func (r Router[HandlerFunc, Route]) SubRouter(router apirouter.Router[HandlerFunc, Route], opts SubRouterOptions) (*Router[HandlerFunc, Route], error) { 102 | return &Router[HandlerFunc, Route]{ 103 | router: router, 104 | swaggerSchema: r.swaggerSchema, 105 | context: r.context, 106 | jsonDocumentationPath: r.jsonDocumentationPath, 107 | yamlDocumentationPath: r.yamlDocumentationPath, 108 | pathPrefix: opts.PathPrefix, 109 | }, nil 110 | } 111 | 112 | func generateNewValidOpenapi(openapi *openapi3.T) (*openapi3.T, error) { 113 | if openapi == nil { 114 | return nil, fmt.Errorf("openapi is required") 115 | } 116 | if openapi.OpenAPI == "" { 117 | openapi.OpenAPI = defaultOpenapiVersion 118 | } 119 | if openapi.Paths == nil { 120 | openapi.Paths = &openapi3.Paths{} 121 | } 122 | 123 | if openapi.Info == nil { 124 | return nil, fmt.Errorf("openapi info is required") 125 | } 126 | if openapi.Info.Title == "" { 127 | return nil, fmt.Errorf("openapi info title is required") 128 | } 129 | if openapi.Info.Version == "" { 130 | return nil, fmt.Errorf("openapi info version is required") 131 | } 132 | 133 | return openapi, nil 134 | } 135 | 136 | // GenerateAndExposeOpenapi creates a /documentation/json route on router and 137 | // expose the generated swagger 138 | func (r Router[_, _]) GenerateAndExposeOpenapi() error { 139 | if err := r.swaggerSchema.Validate(r.context); err != nil { 140 | return fmt.Errorf("%w: %s", ErrValidatingOAS, err) 141 | } 142 | 143 | jsonSwagger, err := r.swaggerSchema.MarshalJSON() 144 | if err != nil { 145 | return fmt.Errorf("%w json marshal: %s", ErrGenerateOAS, err) 146 | } 147 | r.router.AddRoute(http.MethodGet, r.jsonDocumentationPath, r.router.SwaggerHandler("application/json", jsonSwagger)) 148 | 149 | yamlSwagger, err := yaml.JSONToYAML(jsonSwagger) 150 | if err != nil { 151 | return fmt.Errorf("%w yaml marshal: %s", ErrGenerateOAS, err) 152 | } 153 | r.router.AddRoute(http.MethodGet, r.yamlDocumentationPath, r.router.SwaggerHandler("text/plain", yamlSwagger)) 154 | 155 | return nil 156 | } 157 | 158 | func isValidDocumentationPath(path string) error { 159 | if !strings.HasPrefix(path, "/") { 160 | return fmt.Errorf("invalid path %s. Path should start with '/'", path) 161 | } 162 | return nil 163 | } 164 | -------------------------------------------------------------------------------- /testdata/users_employees.json: -------------------------------------------------------------------------------- 1 | { 2 | "info": { 3 | "title": "test openapi title", 4 | "version": "test openapi version" 5 | }, 6 | "openapi": "3.0.0", 7 | "paths": { 8 | "/employees": { 9 | "get": { 10 | "responses": { 11 | "200": { 12 | "content": { 13 | "application/json": { 14 | "schema": { 15 | "additionalProperties": false, 16 | "properties": { 17 | "organization_name": { 18 | "type": "string" 19 | }, 20 | "users": { 21 | "items": { 22 | "additionalProperties": false, 23 | "properties": { 24 | "address": { 25 | "title": "user address", 26 | "type": "string" 27 | }, 28 | "groups": { 29 | "default": [ 30 | "users" 31 | ], 32 | "items": { 33 | "type": "string" 34 | }, 35 | "title": "groups of the user", 36 | "type": "array" 37 | }, 38 | "name": { 39 | "example": "Jane", 40 | "title": "The user name", 41 | "type": "string" 42 | }, 43 | "phone": { 44 | "title": "mobile number of user", 45 | "type": "integer" 46 | } 47 | }, 48 | "required": [ 49 | "name", 50 | "phone", 51 | "address" 52 | ], 53 | "type": "object" 54 | }, 55 | "type": "array" 56 | } 57 | }, 58 | "required": [ 59 | "organization_name", 60 | "users" 61 | ], 62 | "type": "object" 63 | } 64 | } 65 | }, 66 | "description": "" 67 | } 68 | } 69 | } 70 | }, 71 | "/users": { 72 | "get": { 73 | "responses": { 74 | "200": { 75 | "content": { 76 | "application/json": { 77 | "schema": { 78 | "items": { 79 | "additionalProperties": false, 80 | "properties": { 81 | "address": { 82 | "title": "user address", 83 | "type": "string" 84 | }, 85 | "groups": { 86 | "default": [ 87 | "users" 88 | ], 89 | "items": { 90 | "type": "string" 91 | }, 92 | "title": "groups of the user", 93 | "type": "array" 94 | }, 95 | "name": { 96 | "example": "Jane", 97 | "title": "The user name", 98 | "type": "string" 99 | }, 100 | "phone": { 101 | "title": "mobile number of user", 102 | "type": "integer" 103 | } 104 | }, 105 | "required": [ 106 | "name", 107 | "phone", 108 | "address" 109 | ], 110 | "type": "object" 111 | }, 112 | "type": "array" 113 | } 114 | } 115 | }, 116 | "description": "" 117 | } 118 | } 119 | }, 120 | "post": { 121 | "requestBody": { 122 | "content": { 123 | "application/json": { 124 | "schema": { 125 | "additionalProperties": false, 126 | "properties": { 127 | "address": { 128 | "title": "user address", 129 | "type": "string" 130 | }, 131 | "groups": { 132 | "default": [ 133 | "users" 134 | ], 135 | "items": { 136 | "type": "string" 137 | }, 138 | "title": "groups of the user", 139 | "type": "array" 140 | }, 141 | "name": { 142 | "example": "Jane", 143 | "title": "The user name", 144 | "type": "string" 145 | }, 146 | "phone": { 147 | "title": "mobile number of user", 148 | "type": "integer" 149 | } 150 | }, 151 | "required": [ 152 | "name", 153 | "phone", 154 | "address" 155 | ], 156 | "type": "object" 157 | } 158 | } 159 | } 160 | }, 161 | "responses": { 162 | "201": { 163 | "content": { 164 | "text/html": { 165 | "schema": { 166 | "type": "string" 167 | } 168 | } 169 | }, 170 | "description": "" 171 | }, 172 | "401": { 173 | "content": { 174 | "application/json": { 175 | "schema": { 176 | "additionalProperties": false, 177 | "properties": { 178 | "message": { 179 | "type": "string" 180 | } 181 | }, 182 | "required": [ 183 | "message" 184 | ], 185 | "type": "object" 186 | } 187 | } 188 | }, 189 | "description": "invalid request" 190 | } 191 | } 192 | } 193 | } 194 | } 195 | } 196 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 |
2 | 3 | [![Build Status][github-actions-svg]][github-actions] 4 | [![Coverage Status](https://coveralls.io/repos/github/davidebianchi/gswagger/badge.svg?branch=main)](https://coveralls.io/github/davidebianchi/gswagger?branch=main) 5 | [![Go Report Card][go-report-card]][go-report-card-link] 6 | [![GoDoc][godoc-svg]][godoc-link] 7 | 8 | # gswagger 9 | 10 |
11 | 12 | Generate an openapi spec dynamically based on the types used to handle request and response. 13 | 14 | It works with any router, it is simple to add support to your router implementing the [apirouter](apirouter/router.go) interface. 15 | 16 | The routers supported out of the box are: 17 | 18 | - [gorilla-mux](https://github.com/gorilla/mux) 19 | - [fiber](https://github.com/gofiber/fiber) 20 | - [echo](https://echo.labstack.com/) 21 | 22 | This lib uses [kin-openapi] to automatically generate and serve a swagger file. 23 | 24 | To convert struct to schemas, we use [jsonschema] library. 25 | The struct must contains the appropriate struct tags to be inserted in json schema to generate the schema dynamically. 26 | It is always possible to add a totally custom swagger schema using [kin-openapi]. 27 | 28 | ## Install 29 | 30 | To use it, install with 31 | 32 | ```sh 33 | go get github.com/davidebianchi/gswagger 34 | ``` 35 | 36 | ## Usage 37 | 38 | An example usage of this lib with gorilla mux: 39 | 40 | ```go 41 | context := context.Background() 42 | muxRouter := mux.NewRouter() 43 | 44 | router, _ := swagger.NewRouter(gorilla.NewRouter(muxRouter), swagger.Options{ 45 | Context: context, 46 | Openapi: &openapi3.T{ 47 | Info: &openapi3.Info{ 48 | Title: "my title", 49 | Version: "1.0.0", 50 | }, 51 | }, 52 | }) 53 | 54 | okHandler := func(w http.ResponseWriter, req *http.Request) { 55 | w.WriteHeader(http.StatusOK) 56 | w.Write([]byte("OK")) 57 | } 58 | 59 | type User struct { 60 | Name string `json:"name" jsonschema:"title=The user name,required" jsonschema_extras:"example=Jane"` 61 | PhoneNumber int `json:"phone" jsonschema:"title=mobile number of user"` 62 | Groups []string `json:"groups,omitempty" jsonschema:"title=groups of the user,default=users"` 63 | Address string `json:"address" jsonschema:"title=user address"` 64 | } 65 | type errorResponse struct { 66 | Message string `json:"message"` 67 | } 68 | 69 | router.AddRoute(http.MethodPost, "/users", okHandler, swagger.Definitions{ 70 | RequestBody: &swagger.ContentValue{ 71 | Content: swagger.Content{ 72 | "application/json": {Value: User{}}, 73 | }, 74 | }, 75 | Responses: map[int]swagger.ContentValue{ 76 | 201: { 77 | Content: swagger.Content{ 78 | "text/html": {Value: ""}, 79 | }, 80 | }, 81 | 401: { 82 | Content: swagger.Content{ 83 | "application/json": {Value: &errorResponse{}}, 84 | }, 85 | Description: "invalid request", 86 | }, 87 | }, 88 | }) 89 | 90 | router.AddRoute(http.MethodGet, "/users", okHandler, swagger.Definitions{ 91 | Responses: map[int]swagger.ContentValue{ 92 | 200: { 93 | Content: swagger.Content{ 94 | "application/json": {Value: &[]User{}}, 95 | }, 96 | }, 97 | }, 98 | }) 99 | 100 | carSchema := openapi3.NewObjectSchema().WithProperties(map[string]*openapi3.Schema{ 101 | "foo": openapi3.NewStringSchema(), 102 | "bar": openapi3.NewIntegerSchema().WithMax(15).WithMin(5), 103 | }) 104 | requestBody := openapi3.NewRequestBody().WithJSONSchema(carSchema) 105 | operation := swagger.NewOperation() 106 | operation.AddRequestBody(requestBody) 107 | 108 | router.AddRawRoute(http.MethodPost, "/cars", okHandler, operation) 109 | 110 | router.GenerateAndExposeOpenapi() 111 | ``` 112 | 113 | This configuration will output the schema shown [here](./support/gorilla/testdata/examples-users.json). 114 | 115 | ## Auto generated path params schema 116 | 117 | The path params, if not set in schema, are auto generated from the path. 118 | The format of the path parameters depends on the router library you are using, as explained below. 119 | 120 | ### Gorilla Mux 121 | 122 | Gorilla Mux supports the path parameters as `{someParam}`, for example as in `/users/{userId}`. 123 | 124 | Here is the [example test](./support/gorilla/examples_test.go). 125 | 126 | The generated oas schema will contains `userId`, `carId` and `driverId` as path params set to string. 127 | If only one params is set, you must specify manually all the path params. 128 | 129 | The generated OAS for this test case is visible [here](./support/gorilla/testdata/examples-users.json). 130 | 131 | ### Fiber 132 | Fiber supports the path parameters as `:someParam`, for example as in `/users/:userId`. 133 | 134 | Here is the [example test](./support/fiber/integration_test.go) 135 | 136 | ## SubRouter 137 | 138 | It is possible to create a new sub router from the swagger.Router. 139 | It is possible to add a prefix to all the routes created under the specific router (instead of use the router specific methods, if given, or repeat the prefix for every route). 140 | 141 | It could also be useful if you need a sub router to create a group of APIs which use the same middleware (for example,this could be achieved by the SubRouter features of gorilla mux, for example). 142 | 143 | To see the SubRouter example, please see the integration test of one of the supported routers. 144 | 145 | ### FAQ 146 | 147 | 1. How to add format `binary`? 148 | Formats `date-time`, `email`, `hostname`, `ipv4`, `ipv6`, `uri` could be added with tag `jsonschema`. Others format could be added with tag `jsonschema_extra`. Not all the formats are supported (see discovered unsupported formats [here](#discovered-unsupported-schema-features)). 149 | 150 | 1. How to add a swagger with `allOf`? 151 | You can create manually a swagger with `allOf` using the `AddRawRoute` method. 152 | 153 | 1. How to add a swagger with `anyOf`? 154 | You can create manually a swagger with `anyOf` using the `AddRawRoute` method. 155 | 156 | 1. How to add a swagger with `oneOf`? 157 | You can create manually a swagger with `oneOf` using the `AddRawRoute` method, or use the [jsonschema] struct tag. 158 | 159 | #### Discovered unsupported schema features 160 | 161 | *Formats*: 162 | 163 | - `uuid` is unsupported by [kin-openapi] 164 | 165 | ## Versioning 166 | 167 | We use [SemVer][semver] for versioning. For the versions available, 168 | see the [tags on this repository](https://github.com/davidebianchi/gswagger/tags). 169 | 170 | 171 | [kin-openapi]: https://github.com/getkin/kin-openapi 172 | [jsonschema]: https://github.com/mia-platform/jsonschema 173 | [github-actions]: https://github.com/davidebianchi/gswagger/actions 174 | [github-actions-svg]: https://github.com/davidebianchi/gswagger/workflows/Test%20and%20build/badge.svg 175 | [godoc-svg]: https://godoc.org/github.com/davidebianchi/gswagger?status.svg 176 | [godoc-link]: https://godoc.org/github.com/davidebianchi/gswagger 177 | [go-report-card]: https://goreportcard.com/badge/github.com/davidebianchi/gswagger 178 | [go-report-card-link]: https://goreportcard.com/report/github.com/davidebianchi/gswagger 179 | [semver]: https://semver.org/ 180 | -------------------------------------------------------------------------------- /go.sum: -------------------------------------------------------------------------------- 1 | github.com/andybalholm/brotli v1.0.5 h1:8uQZIdzKmjc/iuPu7O2ioW48L81FgatrcpfFmiq/cCs= 2 | github.com/andybalholm/brotli v1.0.5/go.mod h1:fO7iG3H7G2nSZ7m0zPUDn85XEX2GTukHGRSepvi9Eig= 3 | github.com/bahlo/generic-list-go v0.2.0 h1:5sz/EEAK+ls5wF+NeqDpk5+iNdMDXrh3z3nPnH1Wvgk= 4 | github.com/bahlo/generic-list-go v0.2.0/go.mod h1:2KvAjgMlE5NNynlg/5iLrrCCZ2+5xWbdbCW3pNTGyYg= 5 | github.com/buger/jsonparser v1.1.1 h1:2PnMjfWD7wBILjqQbt530v576A/cAbQvEW9gGIpYMUs= 6 | github.com/buger/jsonparser v1.1.1/go.mod h1:6RYKKt7H4d4+iWqouImQ9R2FZql3VbhNgx27UK13J/0= 7 | github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c= 8 | github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= 9 | github.com/getkin/kin-openapi v0.131.0 h1:NO2UeHnFKRYhZ8wg6Nyh5Cq7dHk4suQQr72a4pMrDxE= 10 | github.com/getkin/kin-openapi v0.131.0/go.mod h1:3OlG51PCYNsPByuiMB0t4fjnNlIDnaEDsjiKUV8nL58= 11 | github.com/ghodss/yaml v1.0.0 h1:wQHKEahhL6wmXdzwWG11gIVCkOv05bNOh+Rxn0yngAk= 12 | github.com/ghodss/yaml v1.0.0/go.mod h1:4dBDuWmgqj2HViK6kFavaiC9ZROes6MMH2rRYeMEF04= 13 | github.com/go-openapi/jsonpointer v0.21.0 h1:YgdVicSA9vH5RiHs9TZW5oyafXZFc6+2Vc1rr/O9oNQ= 14 | github.com/go-openapi/jsonpointer v0.21.0/go.mod h1:IUyH9l/+uyhIYQ/PXVA41Rexl+kOkAPDdXEYns6fzUY= 15 | github.com/go-openapi/swag v0.23.0 h1:vsEVJDUo2hPJ2tu0/Xc+4noaxyEffXNIs3cOULZ+GrE= 16 | github.com/go-openapi/swag v0.23.0/go.mod h1:esZ8ITTYEsH1V2trKHjAN8Ai7xHb8RV+YSZ577vPjgQ= 17 | github.com/go-test/deep v1.0.8 h1:TDsG77qcSprGbC6vTN8OuXp5g+J+b5Pcguhf7Zt61VM= 18 | github.com/go-test/deep v1.0.8/go.mod h1:5C2ZWiW0ErCdrYzpqxLbTX7MG14M9iiw8DgHncVwcsE= 19 | github.com/gofiber/fiber/v2 v2.52.5 h1:tWoP1MJQjGEe4GB5TUGOi7P2E0ZMMRx5ZTG4rT+yGMo= 20 | github.com/gofiber/fiber/v2 v2.52.5/go.mod h1:KEOE+cXMhXG0zHc9d8+E38hoX+ZN7bhOtgeF2oT6jrQ= 21 | github.com/google/uuid v1.5.0 h1:1p67kYwdtXjb0gL0BPiP1Av9wiZPo5A8z2cWkTZ+eyU= 22 | github.com/google/uuid v1.5.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo= 23 | github.com/gorilla/mux v1.8.1 h1:TuBL49tXwgrFYWhqrNgrUNEY92u81SPhu7sTdzQEiWY= 24 | github.com/gorilla/mux v1.8.1/go.mod h1:AKf9I4AEqPTmMytcMc0KkNouC66V3BtZ4qD5fmWSiMQ= 25 | github.com/invopop/jsonschema v0.12.0 h1:6ovsNSuvn9wEQVOyc72aycBMVQFKz7cPdMJn10CvzRI= 26 | github.com/invopop/jsonschema v0.12.0/go.mod h1:ffZ5Km5SWWRAIN6wbDXItl95euhFz2uON45H2qjYt+0= 27 | github.com/josharian/intern v1.0.0 h1:vlS4z54oSdjm0bgjRigI+G1HpF+tI+9rE5LLzOg8HmY= 28 | github.com/josharian/intern v1.0.0/go.mod h1:5DoeVV0s6jJacbCEi61lwdGj/aVlrQvzHFFd8Hwg//Y= 29 | github.com/klauspost/compress v1.17.0 h1:Rnbp4K9EjcDuVuHtd0dgA4qNuv9yKDYKK1ulpJwgrqM= 30 | github.com/klauspost/compress v1.17.0/go.mod h1:ntbaceVETuRiXiv4DpjP66DpAtAGkEQskQzEyD//IeE= 31 | github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE= 32 | github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk= 33 | github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY= 34 | github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE= 35 | github.com/labstack/echo/v4 v4.12.0 h1:IKpw49IMryVB2p1a4dzwlhP1O2Tf2E0Ir/450lH+kI0= 36 | github.com/labstack/echo/v4 v4.12.0/go.mod h1:UP9Cr2DJXbOK3Kr9ONYzNowSh7HP0aG0ShAyycHSJvM= 37 | github.com/labstack/gommon v0.4.2 h1:F8qTUNXgG1+6WQmqoUWnz8WiEU60mXVVw0P4ht1WRA0= 38 | github.com/labstack/gommon v0.4.2/go.mod h1:QlUFxVM+SNXhDL/Z7YhocGIBYOiwB0mXm1+1bAPHPyU= 39 | github.com/mailru/easyjson v0.7.7 h1:UGYAvKxe3sBsEDzO8ZeWOSlIQfWFlxbzLZe7hwFURr0= 40 | github.com/mailru/easyjson v0.7.7/go.mod h1:xzfreul335JAWq5oZzymOObrkdz5UnU4kGfJJLY9Nlc= 41 | github.com/mattn/go-colorable v0.1.13 h1:fFA4WZxdEF4tXPZVKMLwD8oUnCTTo08duU7wxecdEvA= 42 | github.com/mattn/go-colorable v0.1.13/go.mod h1:7S9/ev0klgBDR4GtXTXX8a3vIGJpMovkB8vQcUbaXHg= 43 | github.com/mattn/go-isatty v0.0.16/go.mod h1:kYGgaQfpe5nmfYZH+SKPsOc2e4SrIfOl2e/yFXSvRLM= 44 | github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY= 45 | github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y= 46 | github.com/mattn/go-runewidth v0.0.15 h1:UNAjwbU9l54TA3KzvqLGxwWjHmMgBUVhBiTjelZgg3U= 47 | github.com/mattn/go-runewidth v0.0.15/go.mod h1:Jdepj2loyihRzMpdS35Xk/zdY8IAYHsh153qUoGf23w= 48 | github.com/mohae/deepcopy v0.0.0-20170929034955-c48cc78d4826 h1:RWengNIwukTxcDr9M+97sNutRR1RKhG96O6jWumTTnw= 49 | github.com/mohae/deepcopy v0.0.0-20170929034955-c48cc78d4826/go.mod h1:TaXosZuwdSHYgviHp1DAtfrULt5eUgsSMsZf+YrPgl8= 50 | github.com/oasdiff/yaml v0.0.0-20250309154309-f31be36b4037 h1:G7ERwszslrBzRxj//JalHPu/3yz+De2J+4aLtSRlHiY= 51 | github.com/oasdiff/yaml v0.0.0-20250309154309-f31be36b4037/go.mod h1:2bpvgLBZEtENV5scfDFEtB/5+1M4hkQhDQrccEJ/qGw= 52 | github.com/oasdiff/yaml3 v0.0.0-20250309153720-d2182401db90 h1:bQx3WeLcUWy+RletIKwUIt4x3t8n2SxavmoclizMb8c= 53 | github.com/oasdiff/yaml3 v0.0.0-20250309153720-d2182401db90/go.mod h1:y5+oSEHCPT/DGrS++Wc/479ERge0zTFxaF8PbGKcg2o= 54 | github.com/perimeterx/marshmallow v1.1.5 h1:a2LALqQ1BlHM8PZblsDdidgv1mWi1DgC2UmX50IvK2s= 55 | github.com/perimeterx/marshmallow v1.1.5/go.mod h1:dsXbUu8CRzfYP5a87xpp0xq9S3u0Vchtcl8we9tYaXw= 56 | github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM= 57 | github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4= 58 | github.com/rivo/uniseg v0.2.0 h1:S1pD9weZBuJdFmowNwbpi7BJ8TNftyUImj/0WQi72jY= 59 | github.com/rivo/uniseg v0.2.0/go.mod h1:J6wj4VEh+S6ZtnVlnTBMWIodfgj8LQOQFoIToxlJtxc= 60 | github.com/rogpeppe/go-internal v1.12.0 h1:exVL4IDcn6na9z1rAb56Vxr+CgyK3nn3O+epU5NdKM8= 61 | github.com/rogpeppe/go-internal v1.12.0/go.mod h1:E+RYuTGaKKdloAfM02xzb0FW3Paa99yedzYV+kq4uf4= 62 | github.com/stretchr/testify v1.9.0 h1:HtqpIVDClZ4nwg75+f6Lvsy/wHu+3BoSGCbBAcpTsTg= 63 | github.com/stretchr/testify v1.9.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY= 64 | github.com/ugorji/go/codec v1.2.7 h1:YPXUKf7fYbp/y8xloBqZOw2qaVggbfwMlI8WM3wZUJ0= 65 | github.com/ugorji/go/codec v1.2.7/go.mod h1:WGN1fab3R1fzQlVQTkfxVtIBhWDRqOviHU95kRgeqEY= 66 | github.com/valyala/bytebufferpool v1.0.0 h1:GqA5TC/0021Y/b9FG4Oi9Mr3q7XYx6KllzawFIhcdPw= 67 | github.com/valyala/bytebufferpool v1.0.0/go.mod h1:6bBcMArwyJ5K/AmCkWv1jt77kVWyCJ6HpOuEn7z0Csc= 68 | github.com/valyala/fasthttp v1.51.0 h1:8b30A5JlZ6C7AS81RsWjYMQmrZG6feChmgAolCl1SqA= 69 | github.com/valyala/fasthttp v1.51.0/go.mod h1:oI2XroL+lI7vdXyYoQk03bXBThfFl2cVdIA3Xl7cH8g= 70 | github.com/valyala/fasttemplate v1.2.2 h1:lxLXG0uE3Qnshl9QyaK6XJxMXlQZELvChBOCmQD0Loo= 71 | github.com/valyala/fasttemplate v1.2.2/go.mod h1:KHLXt3tVN2HBp8eijSv/kGJopbvo7S+qRAEEKiv+SiQ= 72 | github.com/valyala/tcplisten v1.0.0 h1:rBHj/Xf+E1tRGZyWIWwJDiRY0zc1Js+CV5DqwacVSA8= 73 | github.com/valyala/tcplisten v1.0.0/go.mod h1:T0xQ8SeCZGxckz9qRXTfG43PvQ/mcWh7FwZEA7Ioqkc= 74 | github.com/wk8/go-ordered-map/v2 v2.1.8 h1:5h/BUHu93oj4gIdvHHHGsScSTMijfx5PeYkE/fJgbpc= 75 | github.com/wk8/go-ordered-map/v2 v2.1.8/go.mod h1:5nJHM5DyteebpVlHnWMV0rPz6Zp7+xBAnxjb1X5vnTw= 76 | golang.org/x/crypto v0.22.0 h1:g1v0xeRhjcugydODzvb3mEM9SQ0HGp9s/nh3COQ/C30= 77 | golang.org/x/crypto v0.22.0/go.mod h1:vr6Su+7cTlO45qkww3VDJlzDn0ctJvRgYbC2NvXHt+M= 78 | golang.org/x/net v0.24.0 h1:1PcaxkF854Fu3+lvBIx5SYn9wRlBzzcnHZSiaFFAb0w= 79 | golang.org/x/net v0.24.0/go.mod h1:2Q7sJY5mzlzWjKtYUEXSlBWCdyaioyXzRB2RtU8KVE8= 80 | golang.org/x/sys v0.0.0-20220811171246-fbc7d0a398ab/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= 81 | golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= 82 | golang.org/x/sys v0.19.0 h1:q5f1RH2jigJ1MoAWp2KTp3gm5zAGFUTarQZ5U386+4o= 83 | golang.org/x/sys v0.19.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA= 84 | golang.org/x/text v0.14.0 h1:ScX5w1eTa3QqT8oi6+ziP7dTV1S2+ALU0bI+0zXKWiQ= 85 | golang.org/x/text v0.14.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU= 86 | gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0= 87 | gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk= 88 | gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q= 89 | gopkg.in/yaml.v2 v2.4.0 h1:D8xgwECY7CYvx+Y2n4sBz93Jn9JRvxdiyyo8CTfuKaY= 90 | gopkg.in/yaml.v2 v2.4.0/go.mod h1:RDklbk79AGWmwhnvt/jBztapEOGDOx6ZbXqjP6csGnQ= 91 | gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA= 92 | gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM= 93 | -------------------------------------------------------------------------------- /route.go: -------------------------------------------------------------------------------- 1 | package swagger 2 | 3 | import ( 4 | "errors" 5 | "fmt" 6 | "path" 7 | "regexp" 8 | "sort" 9 | "strings" 10 | 11 | "github.com/getkin/kin-openapi/openapi3" 12 | "github.com/invopop/jsonschema" 13 | ) 14 | 15 | var ( 16 | // ErrResponses is thrown if error occurs generating responses schemas. 17 | ErrResponses = errors.New("errors generating responses schema") 18 | // ErrRequestBody is thrown if error occurs generating responses schemas. 19 | ErrRequestBody = errors.New("errors generating request body schema") 20 | // ErrPathParams is thrown if error occurs generating path params schemas. 21 | ErrPathParams = errors.New("errors generating path parameters schema") 22 | // ErrQuerystring is thrown if error occurs generating querystring params schemas. 23 | ErrQuerystring = errors.New("errors generating querystring schema") 24 | ) 25 | 26 | // AddRawRoute add route to router with specific method, path and handler. Add the 27 | // router also to the openapi schema, after validating it 28 | func (r Router[HandlerFunc, Route]) AddRawRoute(method string, routePath string, handler HandlerFunc, operation Operation) (Route, error) { 29 | op := operation.Operation 30 | if op != nil { 31 | err := operation.Validate(r.context) 32 | if err != nil { 33 | return getZero[Route](), err 34 | } 35 | } else { 36 | op = openapi3.NewOperation() 37 | if op.Responses == nil { 38 | op.Responses = openapi3.NewResponses() 39 | } 40 | } 41 | pathWithPrefix := path.Join(r.pathPrefix, routePath) 42 | oasPath := r.router.TransformPathToOasPath(pathWithPrefix) 43 | r.swaggerSchema.AddOperation(oasPath, method, op) 44 | 45 | // Handle, when content-type is json, the request/response marshalling? Maybe with a specific option. 46 | return r.router.AddRoute(method, pathWithPrefix, handler), nil 47 | } 48 | 49 | // Content is the type of a content. 50 | // The key of the map define the content-type. 51 | type Content map[string]Schema 52 | 53 | // Schema contains the value and if properties allow additional properties. 54 | type Schema struct { 55 | Value interface{} 56 | AllowAdditionalProperties bool 57 | } 58 | 59 | type Parameter struct { 60 | Content Content 61 | Schema *Schema 62 | Description string 63 | } 64 | 65 | // ParameterValue is the struct containing the schema or the content information. 66 | // If content is specified, it takes precedence. 67 | type ParameterValue map[string]Parameter 68 | 69 | // ContentValue is the struct containing the content information. 70 | type ContentValue struct { 71 | Content Content 72 | Description string 73 | } 74 | 75 | type SecurityRequirements []SecurityRequirement 76 | type SecurityRequirement map[string][]string 77 | 78 | // Definitions of the route. 79 | // To see how to use, refer to https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md 80 | type Definitions struct { 81 | // Specification extensions https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#specification-extensions 82 | Extensions map[string]interface{} 83 | // Optional field for documentation 84 | Tags []string 85 | Summary string 86 | Description string 87 | Deprecated bool 88 | 89 | // PathParams contains the path parameters. If empty is autocompleted from the path 90 | PathParams ParameterValue 91 | Querystring ParameterValue 92 | Headers ParameterValue 93 | Cookies ParameterValue 94 | RequestBody *ContentValue 95 | Responses map[int]ContentValue 96 | 97 | Security SecurityRequirements 98 | } 99 | 100 | func newOperationFromDefinition(schema Definitions) Operation { 101 | operation := NewOperation() 102 | operation.Responses = &openapi3.Responses{} 103 | operation.Tags = schema.Tags 104 | operation.Extensions = schema.Extensions 105 | operation.addSecurityRequirements(schema.Security) 106 | operation.Description = schema.Description 107 | operation.Summary = schema.Summary 108 | operation.Deprecated = schema.Deprecated 109 | 110 | return operation 111 | } 112 | 113 | const ( 114 | pathParamsType = "path" 115 | queryParamType = "query" 116 | headerParamType = "header" 117 | cookieParamType = "cookie" 118 | ) 119 | 120 | // AddRoute add a route with json schema inferred by passed schema. 121 | func (r Router[HandlerFunc, Route]) AddRoute(method string, path string, handler HandlerFunc, schema Definitions) (Route, error) { 122 | operation := newOperationFromDefinition(schema) 123 | 124 | err := r.resolveRequestBodySchema(schema.RequestBody, operation) 125 | if err != nil { 126 | return getZero[Route](), fmt.Errorf("%w: %s", ErrRequestBody, err) 127 | } 128 | 129 | err = r.resolveResponsesSchema(schema.Responses, operation) 130 | if err != nil { 131 | return getZero[Route](), fmt.Errorf("%w: %s", ErrResponses, err) 132 | } 133 | 134 | oasPath := r.router.TransformPathToOasPath(path) 135 | err = r.resolveParameterSchema(pathParamsType, getPathParamsAutoComplete(schema, oasPath), operation) 136 | if err != nil { 137 | return getZero[Route](), fmt.Errorf("%w: %s", ErrPathParams, err) 138 | } 139 | 140 | err = r.resolveParameterSchema(queryParamType, schema.Querystring, operation) 141 | if err != nil { 142 | return getZero[Route](), fmt.Errorf("%w: %s", ErrPathParams, err) 143 | } 144 | 145 | err = r.resolveParameterSchema(headerParamType, schema.Headers, operation) 146 | if err != nil { 147 | return getZero[Route](), fmt.Errorf("%w: %s", ErrPathParams, err) 148 | } 149 | 150 | err = r.resolveParameterSchema(cookieParamType, schema.Cookies, operation) 151 | if err != nil { 152 | return getZero[Route](), fmt.Errorf("%w: %s", ErrPathParams, err) 153 | } 154 | 155 | return r.AddRawRoute(method, path, handler, operation) 156 | } 157 | 158 | func (r Router[_, _]) getSchemaFromInterface(v interface{}, allowAdditionalProperties bool) (*openapi3.Schema, error) { 159 | if v == nil { 160 | return &openapi3.Schema{}, nil 161 | } 162 | 163 | reflector := &jsonschema.Reflector{ 164 | DoNotReference: true, 165 | AllowAdditionalProperties: allowAdditionalProperties, 166 | Anonymous: true, 167 | } 168 | 169 | jsonSchema := reflector.Reflect(v) 170 | jsonSchema.Version = "" 171 | // Empty definitions. Definitions are not valid in openapi3, which use components. 172 | // In the future, we could add an option to fill the components in openapi spec. 173 | jsonSchema.Definitions = nil 174 | 175 | data, err := jsonSchema.MarshalJSON() 176 | if err != nil { 177 | return nil, err 178 | } 179 | 180 | schema := openapi3.NewSchema() 181 | err = schema.UnmarshalJSON(data) 182 | if err != nil { 183 | return nil, err 184 | } 185 | 186 | return schema, nil 187 | } 188 | 189 | func (r Router[_, _]) resolveRequestBodySchema(bodySchema *ContentValue, operation Operation) error { 190 | if bodySchema == nil { 191 | return nil 192 | } 193 | content, err := r.addContentToOASSchema(bodySchema.Content) 194 | if err != nil { 195 | return err 196 | } 197 | 198 | requestBody := openapi3.NewRequestBody().WithContent(content) 199 | 200 | if bodySchema.Description != "" { 201 | requestBody.WithDescription(bodySchema.Description) 202 | } 203 | 204 | operation.AddRequestBody(requestBody) 205 | return nil 206 | } 207 | 208 | func (r Router[_, _]) resolveResponsesSchema(responses map[int]ContentValue, operation Operation) error { 209 | if responses == nil { 210 | operation.Responses = openapi3.NewResponses() 211 | } 212 | for statusCode, v := range responses { 213 | response := openapi3.NewResponse() 214 | content, err := r.addContentToOASSchema(v.Content) 215 | if err != nil { 216 | return err 217 | } 218 | response = response.WithContent(content) 219 | response = response.WithDescription(v.Description) 220 | 221 | operation.AddResponse(statusCode, response) 222 | } 223 | 224 | return nil 225 | } 226 | 227 | func (r Router[_, _]) resolveParameterSchema(paramType string, paramConfig ParameterValue, operation Operation) error { 228 | var keys = make([]string, 0, len(paramConfig)) 229 | for k := range paramConfig { 230 | keys = append(keys, k) 231 | } 232 | sort.Strings(keys) 233 | 234 | for _, key := range keys { 235 | v := paramConfig[key] 236 | var param *openapi3.Parameter 237 | switch paramType { 238 | case pathParamsType: 239 | param = openapi3.NewPathParameter(key) 240 | case queryParamType: 241 | param = openapi3.NewQueryParameter(key) 242 | case headerParamType: 243 | param = openapi3.NewHeaderParameter(key) 244 | case cookieParamType: 245 | param = openapi3.NewCookieParameter(key) 246 | default: 247 | return fmt.Errorf("invalid param type") 248 | } 249 | 250 | if v.Description != "" { 251 | param = param.WithDescription(v.Description) 252 | } 253 | 254 | if v.Content != nil { 255 | content, err := r.addContentToOASSchema(v.Content) 256 | if err != nil { 257 | return err 258 | } 259 | param.Content = content 260 | } else { 261 | schema := openapi3.NewSchema() 262 | if v.Schema != nil { 263 | var err error 264 | schema, err = r.getSchemaFromInterface(v.Schema.Value, v.Schema.AllowAdditionalProperties) 265 | if err != nil { 266 | return err 267 | } 268 | } 269 | param.WithSchema(schema) 270 | } 271 | 272 | operation.AddParameter(param) 273 | } 274 | 275 | return nil 276 | } 277 | 278 | func (r Router[_, _]) addContentToOASSchema(content Content) (openapi3.Content, error) { 279 | oasContent := openapi3.NewContent() 280 | for k, v := range content { 281 | var err error 282 | schema, err := r.getSchemaFromInterface(v.Value, v.AllowAdditionalProperties) 283 | if err != nil { 284 | return nil, err 285 | } 286 | oasContent[k] = openapi3.NewMediaType().WithSchema(schema) 287 | } 288 | return oasContent, nil 289 | } 290 | 291 | func getPathParamsAutoComplete(schema Definitions, path string) ParameterValue { 292 | if schema.PathParams == nil { 293 | re := regexp.MustCompile(`\{([^}]+)\}`) 294 | segments := strings.Split(path, "/") 295 | for _, segment := range segments { 296 | params := re.FindAllStringSubmatch(segment, -1) 297 | if len(params) == 0 { 298 | continue 299 | } 300 | if schema.PathParams == nil { 301 | schema.PathParams = make(ParameterValue) 302 | } 303 | for _, param := range params { 304 | schema.PathParams[param[1]] = Parameter{ 305 | Schema: &Schema{Value: ""}, 306 | } 307 | } 308 | } 309 | } 310 | return schema.PathParams 311 | } 312 | 313 | func getZero[T any]() T { 314 | var result T 315 | return result 316 | } 317 | -------------------------------------------------------------------------------- /main_test.go: -------------------------------------------------------------------------------- 1 | package swagger 2 | 3 | import ( 4 | "context" 5 | "fmt" 6 | "io" 7 | "net/http" 8 | "net/http/httptest" 9 | "os" 10 | "strings" 11 | "testing" 12 | 13 | "github.com/davidebianchi/gswagger/support/gorilla" 14 | "github.com/getkin/kin-openapi/openapi3" 15 | "github.com/gorilla/mux" 16 | "github.com/stretchr/testify/require" 17 | ) 18 | 19 | func TestNewRouter(t *testing.T) { 20 | muxRouter := mux.NewRouter() 21 | mAPIRouter := gorilla.NewRouter(muxRouter) 22 | 23 | info := &openapi3.Info{ 24 | Title: "my title", 25 | Version: "my version", 26 | } 27 | openapi := &openapi3.T{ 28 | Info: info, 29 | Paths: &openapi3.Paths{}, 30 | } 31 | 32 | t.Run("not ok - invalid Openapi option", func(t *testing.T) { 33 | r, err := NewRouter(mAPIRouter, Options{}) 34 | 35 | require.Nil(t, r) 36 | require.EqualError(t, err, fmt.Sprintf("%s: openapi is required", ErrValidatingOAS)) 37 | }) 38 | 39 | t.Run("ok - with default context", func(t *testing.T) { 40 | r, err := NewRouter(mAPIRouter, Options{ 41 | Openapi: openapi, 42 | }) 43 | 44 | require.NoError(t, err) 45 | require.Equal(t, &Router[gorilla.HandlerFunc, gorilla.Route]{ 46 | context: context.Background(), 47 | router: mAPIRouter, 48 | swaggerSchema: openapi, 49 | jsonDocumentationPath: DefaultJSONDocumentationPath, 50 | yamlDocumentationPath: DefaultYAMLDocumentationPath, 51 | }, r) 52 | }) 53 | 54 | t.Run("ok - with custom context", func(t *testing.T) { 55 | type key struct{} 56 | ctx := context.WithValue(context.Background(), key{}, "value") 57 | r, err := NewRouter(mAPIRouter, Options{ 58 | Openapi: openapi, 59 | Context: ctx, 60 | }) 61 | 62 | require.NoError(t, err) 63 | require.Equal(t, &Router[gorilla.HandlerFunc, gorilla.Route]{ 64 | context: ctx, 65 | router: mAPIRouter, 66 | swaggerSchema: openapi, 67 | jsonDocumentationPath: DefaultJSONDocumentationPath, 68 | yamlDocumentationPath: DefaultYAMLDocumentationPath, 69 | }, r) 70 | }) 71 | 72 | t.Run("ok - with custom docs paths", func(t *testing.T) { 73 | type key struct{} 74 | ctx := context.WithValue(context.Background(), key{}, "value") 75 | r, err := NewRouter(mAPIRouter, Options{ 76 | Openapi: openapi, 77 | Context: ctx, 78 | JSONDocumentationPath: "/json/path", 79 | YAMLDocumentationPath: "/yaml/path", 80 | }) 81 | 82 | require.NoError(t, err) 83 | require.Equal(t, &Router[gorilla.HandlerFunc, gorilla.Route]{ 84 | context: ctx, 85 | router: mAPIRouter, 86 | swaggerSchema: openapi, 87 | jsonDocumentationPath: "/json/path", 88 | yamlDocumentationPath: "/yaml/path", 89 | }, r) 90 | }) 91 | 92 | t.Run("ko - json documentation path does not start with /", func(t *testing.T) { 93 | type key struct{} 94 | ctx := context.WithValue(context.Background(), key{}, "value") 95 | r, err := NewRouter(mAPIRouter, Options{ 96 | Openapi: openapi, 97 | Context: ctx, 98 | JSONDocumentationPath: "json/path", 99 | YAMLDocumentationPath: "/yaml/path", 100 | }) 101 | 102 | require.EqualError(t, err, "invalid path json/path. Path should start with '/'") 103 | require.Nil(t, r) 104 | }) 105 | 106 | t.Run("ko - yaml documentation path does not start with /", func(t *testing.T) { 107 | type key struct{} 108 | ctx := context.WithValue(context.Background(), key{}, "value") 109 | r, err := NewRouter(mAPIRouter, Options{ 110 | Openapi: openapi, 111 | Context: ctx, 112 | JSONDocumentationPath: "/json/path", 113 | YAMLDocumentationPath: "yaml/path", 114 | }) 115 | 116 | require.EqualError(t, err, "invalid path yaml/path. Path should start with '/'") 117 | require.Nil(t, r) 118 | }) 119 | } 120 | 121 | func TestGenerateValidSwagger(t *testing.T) { 122 | t.Run("not ok - empty openapi info", func(t *testing.T) { 123 | openapi := &openapi3.T{} 124 | 125 | openapi, err := generateNewValidOpenapi(openapi) 126 | require.Nil(t, openapi) 127 | require.EqualError(t, err, "openapi info is required") 128 | }) 129 | 130 | t.Run("not ok - empty info title", func(t *testing.T) { 131 | openapi := &openapi3.T{ 132 | Info: &openapi3.Info{}, 133 | } 134 | 135 | openapi, err := generateNewValidOpenapi(openapi) 136 | require.Nil(t, openapi) 137 | require.EqualError(t, err, "openapi info title is required") 138 | }) 139 | 140 | t.Run("not ok - empty info version", func(t *testing.T) { 141 | openapi := &openapi3.T{ 142 | Info: &openapi3.Info{ 143 | Title: "title", 144 | }, 145 | } 146 | 147 | openapi, err := generateNewValidOpenapi(openapi) 148 | require.Nil(t, openapi) 149 | require.EqualError(t, err, "openapi info version is required") 150 | }) 151 | 152 | t.Run("ok - custom openapi", func(t *testing.T) { 153 | openapi := &openapi3.T{ 154 | Info: &openapi3.Info{}, 155 | } 156 | 157 | openapi, err := generateNewValidOpenapi(openapi) 158 | require.Nil(t, openapi) 159 | require.EqualError(t, err, "openapi info title is required") 160 | }) 161 | 162 | t.Run("not ok - openapi is required", func(t *testing.T) { 163 | openapi, err := generateNewValidOpenapi(nil) 164 | require.Nil(t, openapi) 165 | require.EqualError(t, err, "openapi is required") 166 | }) 167 | 168 | t.Run("ok", func(t *testing.T) { 169 | info := &openapi3.Info{ 170 | Title: "my title", 171 | Version: "my version", 172 | } 173 | openapi := &openapi3.T{ 174 | Info: info, 175 | } 176 | 177 | openapi, err := generateNewValidOpenapi(openapi) 178 | require.NoError(t, err) 179 | require.Equal(t, &openapi3.T{ 180 | OpenAPI: defaultOpenapiVersion, 181 | Info: info, 182 | Paths: &openapi3.Paths{}, 183 | }, openapi) 184 | }) 185 | } 186 | 187 | func TestGenerateAndExposeSwagger(t *testing.T) { 188 | t.Run("fails openapi validation", func(t *testing.T) { 189 | mRouter := mux.NewRouter() 190 | router, err := NewRouter(gorilla.NewRouter(mRouter), Options{ 191 | Openapi: &openapi3.T{ 192 | Info: &openapi3.Info{ 193 | Title: "title", 194 | Version: "version", 195 | }, 196 | Components: &openapi3.Components{ 197 | Schemas: map[string]*openapi3.SchemaRef{ 198 | "&%": {}, 199 | }, 200 | }, 201 | }, 202 | }) 203 | require.NoError(t, err) 204 | 205 | err = router.GenerateAndExposeOpenapi() 206 | require.Error(t, err) 207 | require.True(t, strings.HasPrefix(err.Error(), fmt.Sprintf("%s:", ErrValidatingOAS))) 208 | }) 209 | 210 | t.Run("correctly expose json documentation from loaded openapi file", func(t *testing.T) { 211 | mRouter := mux.NewRouter() 212 | 213 | openapi, err := openapi3.NewLoader().LoadFromFile("testdata/users_employees.json") 214 | require.NoError(t, err) 215 | 216 | router, err := NewRouter(gorilla.NewRouter(mRouter), Options{ 217 | Openapi: openapi, 218 | }) 219 | require.NoError(t, err) 220 | 221 | err = router.GenerateAndExposeOpenapi() 222 | require.NoError(t, err) 223 | 224 | w := httptest.NewRecorder() 225 | req := httptest.NewRequest(http.MethodGet, DefaultJSONDocumentationPath, nil) 226 | mRouter.ServeHTTP(w, req) 227 | 228 | require.Equal(t, http.StatusOK, w.Result().StatusCode) 229 | require.True(t, strings.Contains(w.Result().Header.Get("content-type"), "application/json")) 230 | 231 | body := readBody(t, w.Result().Body) 232 | actual, err := os.ReadFile("testdata/users_employees.json") 233 | require.NoError(t, err) 234 | require.JSONEq(t, string(actual), body) 235 | }) 236 | 237 | t.Run("correctly expose json documentation from loaded openapi file - custom path", func(t *testing.T) { 238 | mRouter := mux.NewRouter() 239 | 240 | openapi, err := openapi3.NewLoader().LoadFromFile("testdata/users_employees.json") 241 | require.NoError(t, err) 242 | 243 | router, err := NewRouter(gorilla.NewRouter(mRouter), Options{ 244 | Openapi: openapi, 245 | JSONDocumentationPath: "/custom/path", 246 | }) 247 | require.NoError(t, err) 248 | 249 | err = router.GenerateAndExposeOpenapi() 250 | require.NoError(t, err) 251 | 252 | w := httptest.NewRecorder() 253 | req := httptest.NewRequest(http.MethodGet, "/custom/path", nil) 254 | mRouter.ServeHTTP(w, req) 255 | 256 | require.Equal(t, http.StatusOK, w.Result().StatusCode) 257 | require.True(t, strings.Contains(w.Result().Header.Get("content-type"), "application/json")) 258 | 259 | body := readBody(t, w.Result().Body) 260 | actual, err := os.ReadFile("testdata/users_employees.json") 261 | require.NoError(t, err) 262 | require.JSONEq(t, string(actual), body) 263 | }) 264 | 265 | t.Run("correctly expose yaml documentation from loaded openapi file", func(t *testing.T) { 266 | mRouter := mux.NewRouter() 267 | 268 | openapi, err := openapi3.NewLoader().LoadFromFile("testdata/users_employees.json") 269 | require.NoError(t, err) 270 | 271 | router, err := NewRouter(gorilla.NewRouter(mRouter), Options{ 272 | Openapi: openapi, 273 | }) 274 | require.NoError(t, err) 275 | 276 | err = router.GenerateAndExposeOpenapi() 277 | require.NoError(t, err) 278 | 279 | w := httptest.NewRecorder() 280 | req := httptest.NewRequest(http.MethodGet, DefaultYAMLDocumentationPath, nil) 281 | mRouter.ServeHTTP(w, req) 282 | 283 | require.Equal(t, http.StatusOK, w.Result().StatusCode) 284 | require.True(t, strings.Contains(w.Result().Header.Get("content-type"), "text/plain")) 285 | 286 | body := readBody(t, w.Result().Body) 287 | expected, err := os.ReadFile("testdata/users_employees.yaml") 288 | require.NoError(t, err) 289 | require.YAMLEq(t, string(expected), body, string(body)) 290 | }) 291 | 292 | t.Run("correctly expose yaml documentation from loaded openapi file - custom path", func(t *testing.T) { 293 | mRouter := mux.NewRouter() 294 | 295 | openapi, err := openapi3.NewLoader().LoadFromFile("testdata/users_employees.json") 296 | require.NoError(t, err) 297 | 298 | router, err := NewRouter(gorilla.NewRouter(mRouter), Options{ 299 | Openapi: openapi, 300 | YAMLDocumentationPath: "/custom/path", 301 | }) 302 | require.NoError(t, err) 303 | 304 | err = router.GenerateAndExposeOpenapi() 305 | require.NoError(t, err) 306 | 307 | w := httptest.NewRecorder() 308 | req := httptest.NewRequest(http.MethodGet, "/custom/path", nil) 309 | mRouter.ServeHTTP(w, req) 310 | 311 | require.Equal(t, http.StatusOK, w.Result().StatusCode) 312 | require.True(t, strings.Contains(w.Result().Header.Get("content-type"), "text/plain")) 313 | 314 | body := readBody(t, w.Result().Body) 315 | expected, err := os.ReadFile("testdata/users_employees.yaml") 316 | require.NoError(t, err) 317 | require.YAMLEq(t, string(expected), body, string(body)) 318 | }) 319 | 320 | t.Run("ok - subrouter", func(t *testing.T) { 321 | mRouter := mux.NewRouter() 322 | 323 | router, err := NewRouter(gorilla.NewRouter(mRouter), Options{ 324 | Openapi: &openapi3.T{ 325 | Info: &openapi3.Info{ 326 | Title: "test openapi title", 327 | Version: "test openapi version", 328 | }, 329 | }, 330 | JSONDocumentationPath: "/custom/path", 331 | }) 332 | require.NoError(t, err) 333 | 334 | router.AddRoute(http.MethodGet, "/foo", func(w http.ResponseWriter, req *http.Request) { 335 | w.WriteHeader(http.StatusOK) 336 | w.Write([]byte("ok")) 337 | }, Definitions{}) 338 | 339 | mSubRouter := mRouter.NewRoute().Subrouter() 340 | subrouter, err := router.SubRouter(gorilla.NewRouter(mSubRouter), SubRouterOptions{ 341 | PathPrefix: "/prefix", 342 | }) 343 | require.NoError(t, err) 344 | 345 | _, err = subrouter.AddRoute(http.MethodGet, "/taz", func(w http.ResponseWriter, req *http.Request) { 346 | w.WriteHeader(http.StatusOK) 347 | w.Write([]byte("ok")) 348 | }, Definitions{}) 349 | require.NoError(t, err) 350 | 351 | t.Run("add route with path equal to prefix path", func(t *testing.T) { 352 | _, err = subrouter.AddRoute(http.MethodGet, "", func(w http.ResponseWriter, req *http.Request) { 353 | w.WriteHeader(http.StatusOK) 354 | w.Write([]byte("ok")) 355 | }, Definitions{}) 356 | require.NoError(t, err) 357 | }) 358 | 359 | err = router.GenerateAndExposeOpenapi() 360 | require.NoError(t, err) 361 | 362 | w := httptest.NewRecorder() 363 | req := httptest.NewRequest(http.MethodGet, "/custom/path", nil) 364 | mRouter.ServeHTTP(w, req) 365 | 366 | require.Equal(t, http.StatusOK, w.Result().StatusCode) 367 | require.True(t, strings.Contains(w.Result().Header.Get("content-type"), "application/json")) 368 | 369 | body := readBody(t, w.Result().Body) 370 | actual, err := os.ReadFile("testdata/subrouter.json") 371 | require.NoError(t, err) 372 | require.JSONEq(t, string(actual), body) 373 | 374 | t.Run("test request /prefix", func(t *testing.T) { 375 | w := httptest.NewRecorder() 376 | req := httptest.NewRequest(http.MethodGet, "/prefix", nil) 377 | mRouter.ServeHTTP(w, req) 378 | 379 | require.Equal(t, http.StatusOK, w.Result().StatusCode) 380 | }) 381 | 382 | t.Run("test request /prefix/taz", func(t *testing.T) { 383 | w := httptest.NewRecorder() 384 | req := httptest.NewRequest(http.MethodGet, "/prefix/taz", nil) 385 | mRouter.ServeHTTP(w, req) 386 | 387 | require.Equal(t, http.StatusOK, w.Result().StatusCode) 388 | }) 389 | 390 | t.Run("test request /foo", func(t *testing.T) { 391 | w := httptest.NewRecorder() 392 | req := httptest.NewRequest(http.MethodGet, "/foo", nil) 393 | mRouter.ServeHTTP(w, req) 394 | 395 | require.Equal(t, http.StatusOK, w.Result().StatusCode) 396 | }) 397 | }) 398 | 399 | t.Run("ok - new router with path prefix", func(t *testing.T) { 400 | mRouter := mux.NewRouter() 401 | 402 | router, err := NewRouter(gorilla.NewRouter(mRouter), Options{ 403 | Openapi: &openapi3.T{ 404 | Info: &openapi3.Info{ 405 | Title: "test openapi title", 406 | Version: "test openapi version", 407 | }, 408 | }, 409 | JSONDocumentationPath: "/custom/path", 410 | PathPrefix: "/prefix", 411 | }) 412 | require.NoError(t, err) 413 | 414 | router.AddRoute(http.MethodGet, "/foo", func(w http.ResponseWriter, req *http.Request) { 415 | w.WriteHeader(http.StatusOK) 416 | w.Write([]byte("ok")) 417 | }, Definitions{}) 418 | 419 | err = router.GenerateAndExposeOpenapi() 420 | require.NoError(t, err) 421 | 422 | w := httptest.NewRecorder() 423 | req := httptest.NewRequest(http.MethodGet, "/custom/path", nil) 424 | mRouter.ServeHTTP(w, req) 425 | 426 | require.Equal(t, http.StatusOK, w.Result().StatusCode) 427 | require.True(t, strings.Contains(w.Result().Header.Get("content-type"), "application/json")) 428 | 429 | body := readBody(t, w.Result().Body) 430 | actual, err := os.ReadFile("testdata/router_with_prefix.json") 431 | require.NoError(t, err) 432 | require.JSONEq(t, string(actual), body, body) 433 | }) 434 | } 435 | 436 | func readBody(t *testing.T, requestBody io.ReadCloser) string { 437 | t.Helper() 438 | 439 | body, err := io.ReadAll(requestBody) 440 | require.NoError(t, err) 441 | 442 | return string(body) 443 | } 444 | -------------------------------------------------------------------------------- /route_test.go: -------------------------------------------------------------------------------- 1 | package swagger 2 | 3 | import ( 4 | "context" 5 | "fmt" 6 | "net/http" 7 | "net/http/httptest" 8 | "os" 9 | "testing" 10 | 11 | "github.com/davidebianchi/gswagger/support/gorilla" 12 | "github.com/getkin/kin-openapi/openapi3" 13 | "github.com/gorilla/mux" 14 | "github.com/stretchr/testify/require" 15 | ) 16 | 17 | const jsonType = "application/json" 18 | const formDataType = "multipart/form-data" 19 | 20 | type TestRouter = Router[gorilla.HandlerFunc, gorilla.Route] 21 | 22 | func TestAddRoutes(t *testing.T) { 23 | type User struct { 24 | Name string `json:"name" jsonschema:"title=The user name,required" jsonschema_extras:"example=Jane"` 25 | PhoneNumber int `json:"phone" jsonschema:"title=mobile number of user"` 26 | Groups []string `json:"groups,omitempty" jsonschema:"title=groups of the user,default=users"` 27 | Address string `json:"address" jsonschema:"title=user address"` 28 | } 29 | type Users []User 30 | type errorResponse struct { 31 | Message string `json:"message"` 32 | } 33 | 34 | type Employees struct { 35 | OrganizationName string `json:"organization_name"` 36 | Users Users `json:"users" jsonschema:"selected users"` 37 | } 38 | type FormData struct { 39 | ID string `json:"id,omitempty"` 40 | Address struct { 41 | Street string `json:"street,omitempty"` 42 | City string `json:"city,omitempty"` 43 | } `json:"address,omitempty"` 44 | ProfileImage string `json:"profileImage,omitempty" jsonschema_extras:"format=binary"` 45 | } 46 | 47 | type UserProfileRequest struct { 48 | FirstName string `json:"firstName" jsonschema:"title=user first name"` 49 | LastName string `json:"lastName" jsonschema:"title=user last name"` 50 | Metadata interface{} `json:"metadata,omitempty" jsonschema:"title=custom properties,oneof_type=string;number"` 51 | UserType string `json:"userType,omitempty" jsonschema:"title=type of user,enum=simple,enum=advanced"` 52 | } 53 | 54 | okHandler := func(w http.ResponseWriter, req *http.Request) { 55 | w.WriteHeader(http.StatusOK) 56 | w.Write([]byte("OK")) 57 | } 58 | 59 | tests := []struct { 60 | name string 61 | routes func(t *testing.T, router *TestRouter) 62 | fixturesPath string 63 | testPath string 64 | testMethod string 65 | }{ 66 | { 67 | name: "no routes", 68 | routes: func(t *testing.T, router *TestRouter) {}, 69 | fixturesPath: "testdata/empty.json", 70 | }, 71 | { 72 | name: "empty route schema", 73 | routes: func(t *testing.T, router *TestRouter) { 74 | _, err := router.AddRoute(http.MethodPost, "/", okHandler, Definitions{}) 75 | require.NoError(t, err) 76 | }, 77 | testPath: "/", 78 | testMethod: http.MethodPost, 79 | fixturesPath: "testdata/empty-route-schema.json", 80 | }, 81 | { 82 | name: "multiple real routes", 83 | routes: func(t *testing.T, router *TestRouter) { 84 | _, err := router.AddRoute(http.MethodPost, "/users", okHandler, Definitions{ 85 | RequestBody: &ContentValue{ 86 | Content: Content{ 87 | jsonType: {Value: User{}}, 88 | }, 89 | }, 90 | Responses: map[int]ContentValue{ 91 | 201: { 92 | Content: Content{ 93 | "text/html": {Value: ""}, 94 | }, 95 | }, 96 | 401: { 97 | Content: Content{ 98 | jsonType: {Value: &errorResponse{}}, 99 | }, 100 | Description: "invalid request", 101 | }, 102 | }, 103 | }) 104 | require.NoError(t, err) 105 | 106 | _, err = router.AddRoute(http.MethodGet, "/users", okHandler, Definitions{ 107 | Responses: map[int]ContentValue{ 108 | 200: { 109 | Content: Content{ 110 | jsonType: {Value: &Users{}}, 111 | }, 112 | }, 113 | }, 114 | }) 115 | require.NoError(t, err) 116 | 117 | _, err = router.AddRoute(http.MethodGet, "/employees", okHandler, Definitions{ 118 | Responses: map[int]ContentValue{ 119 | 200: { 120 | Content: Content{ 121 | jsonType: {Value: &Employees{}}, 122 | }, 123 | }, 124 | }, 125 | }) 126 | require.NoError(t, err) 127 | }, 128 | testPath: "/users", 129 | fixturesPath: "testdata/users_employees.json", 130 | }, 131 | { 132 | name: "multipart request body", 133 | routes: func(t *testing.T, router *TestRouter) { 134 | _, err := router.AddRoute(http.MethodPost, "/files", okHandler, Definitions{ 135 | RequestBody: &ContentValue{ 136 | Content: Content{ 137 | formDataType: { 138 | Value: &FormData{}, 139 | AllowAdditionalProperties: true, 140 | }, 141 | }, 142 | Description: "upload file", 143 | }, 144 | Responses: map[int]ContentValue{ 145 | 200: { 146 | Content: Content{ 147 | jsonType: { 148 | Value: "", 149 | }, 150 | }, 151 | }, 152 | }, 153 | }) 154 | require.NoError(t, err) 155 | }, 156 | testPath: "/files", 157 | testMethod: http.MethodPost, 158 | fixturesPath: "testdata/multipart-requestbody.json", 159 | }, 160 | { 161 | name: "schema with params", 162 | routes: func(t *testing.T, router *TestRouter) { 163 | var number = 0 164 | _, err := router.AddRoute(http.MethodGet, "/users/{userId}", okHandler, Definitions{ 165 | PathParams: ParameterValue{ 166 | "userId": { 167 | Schema: &Schema{Value: number}, 168 | Description: "userId is a number above 0", 169 | }, 170 | }, 171 | }) 172 | require.NoError(t, err) 173 | 174 | _, err = router.AddRoute(http.MethodGet, "/cars/{carId}/drivers/{driverId}", okHandler, Definitions{ 175 | PathParams: ParameterValue{ 176 | "carId": { 177 | Schema: &Schema{Value: ""}, 178 | }, 179 | "driverId": { 180 | Schema: &Schema{Value: ""}, 181 | }, 182 | }, 183 | }) 184 | require.NoError(t, err) 185 | }, 186 | testPath: "/users/12", 187 | fixturesPath: "testdata/params.json", 188 | }, 189 | { 190 | name: "schema without explicit params autofill them", 191 | routes: func(t *testing.T, router *TestRouter) { 192 | _, err := router.AddRoute(http.MethodGet, "/users/{userId}", okHandler, Definitions{ 193 | Querystring: ParameterValue{ 194 | "query": { 195 | Schema: &Schema{Value: ""}, 196 | }, 197 | }, 198 | }) 199 | require.NoError(t, err) 200 | 201 | _, err = router.AddRoute(http.MethodGet, "/cars/{carId}/drivers/{driverId}", okHandler, Definitions{}) 202 | require.NoError(t, err) 203 | 204 | _, err = router.AddRoute(http.MethodGet, "/files/{name}.{extension}", okHandler, Definitions{}) 205 | require.NoError(t, err) 206 | }, 207 | testPath: "/files/myid.yaml", 208 | fixturesPath: "testdata/params-autofill.json", 209 | }, 210 | { 211 | name: "schema with querystring", 212 | routes: func(t *testing.T, router *TestRouter) { 213 | _, err := router.AddRoute(http.MethodGet, "/projects", okHandler, Definitions{ 214 | Querystring: ParameterValue{ 215 | "projectId": { 216 | Schema: &Schema{Value: ""}, 217 | Description: "projectId is the project id", 218 | }, 219 | }, 220 | }) 221 | require.NoError(t, err) 222 | }, 223 | testPath: "/projects", 224 | fixturesPath: "testdata/query.json", 225 | }, 226 | { 227 | name: "schema with headers", 228 | routes: func(t *testing.T, router *TestRouter) { 229 | _, err := router.AddRoute(http.MethodGet, "/projects", okHandler, Definitions{ 230 | Headers: ParameterValue{ 231 | "foo": { 232 | Schema: &Schema{Value: ""}, 233 | Description: "foo description", 234 | }, 235 | "bar": { 236 | Schema: &Schema{Value: ""}, 237 | }, 238 | }, 239 | }) 240 | require.NoError(t, err) 241 | }, 242 | testPath: "/projects", 243 | fixturesPath: "testdata/headers.json", 244 | }, 245 | { 246 | name: "schema with cookies", 247 | routes: func(t *testing.T, router *TestRouter) { 248 | _, err := router.AddRoute(http.MethodGet, "/projects", okHandler, Definitions{ 249 | Cookies: ParameterValue{ 250 | "debug": { 251 | Schema: &Schema{Value: 0}, 252 | Description: "boolean. Set 0 to disable and 1 to enable", 253 | }, 254 | "csrftoken": { 255 | Schema: &Schema{Value: ""}, 256 | }, 257 | }, 258 | }) 259 | require.NoError(t, err) 260 | }, 261 | testPath: "/projects", 262 | fixturesPath: "testdata/cookies.json", 263 | }, 264 | { 265 | name: "schema defined without value", 266 | routes: func(t *testing.T, router *TestRouter) { 267 | _, err := router.AddRoute(http.MethodPost, "/{id}", okHandler, Definitions{ 268 | RequestBody: &ContentValue{ 269 | Description: "request body without schema", 270 | }, 271 | Responses: map[int]ContentValue{ 272 | 204: {}, 273 | }, 274 | PathParams: ParameterValue{ 275 | "id": {}, 276 | }, 277 | Querystring: ParameterValue{ 278 | "q": {}, 279 | }, 280 | Headers: ParameterValue{ 281 | "key": {}, 282 | }, 283 | Cookies: ParameterValue{ 284 | "cookie1": {}, 285 | }, 286 | }) 287 | require.NoError(t, err) 288 | }, 289 | testPath: "/foobar", 290 | testMethod: http.MethodPost, 291 | fixturesPath: "testdata/schema-no-content.json", 292 | }, 293 | { 294 | name: "allOf schema", 295 | routes: func(t *testing.T, router *TestRouter) { 296 | schema := openapi3.NewAllOfSchema() 297 | schema.AllOf = []*openapi3.SchemaRef{ 298 | { 299 | Value: openapi3.NewFloat64Schema(). 300 | WithMin(1). 301 | WithMax(2), 302 | }, 303 | { 304 | Value: openapi3.NewFloat64Schema(). 305 | WithMin(2). 306 | WithMax(3), 307 | }, 308 | } 309 | 310 | request := openapi3.NewRequestBody().WithJSONSchema(schema) 311 | response := openapi3.NewResponse().WithJSONSchema(schema) 312 | 313 | allOperation := NewOperation() 314 | allOperation.AddResponse(200, response) 315 | allOperation.AddRequestBody(request) 316 | 317 | _, err := router.AddRawRoute(http.MethodPost, "/all-of", okHandler, allOperation) 318 | require.NoError(t, err) 319 | 320 | nestedSchema := openapi3.NewSchema() 321 | nestedSchema.Properties = map[string]*openapi3.SchemaRef{ 322 | "foo": { 323 | Value: openapi3.NewStringSchema(), 324 | }, 325 | "nested": { 326 | Value: schema, 327 | }, 328 | } 329 | responseNested := openapi3.NewResponse().WithJSONSchema(nestedSchema) 330 | nestedAllOfOperation := NewOperation() 331 | nestedAllOfOperation.AddResponse(200, responseNested) 332 | 333 | _, err = router.AddRawRoute(http.MethodGet, "/nested-schema", okHandler, nestedAllOfOperation) 334 | require.NoError(t, err) 335 | }, 336 | fixturesPath: "testdata/allof.json", 337 | }, 338 | { 339 | name: "anyOf schema", 340 | routes: func(t *testing.T, router *TestRouter) { 341 | schema := openapi3.NewAnyOfSchema() 342 | schema.AnyOf = []*openapi3.SchemaRef{ 343 | { 344 | Value: openapi3.NewFloat64Schema(). 345 | WithMin(1). 346 | WithMax(2), 347 | }, 348 | { 349 | Value: openapi3.NewFloat64Schema(). 350 | WithMin(2). 351 | WithMax(3), 352 | }, 353 | } 354 | request := openapi3.NewRequestBody().WithJSONSchema(schema) 355 | response := openapi3.NewResponse().WithJSONSchema(schema) 356 | 357 | allOperation := NewOperation() 358 | allOperation.AddResponse(200, response) 359 | allOperation.AddRequestBody(request) 360 | 361 | _, err := router.AddRawRoute(http.MethodPost, "/any-of", okHandler, allOperation) 362 | require.NoError(t, err) 363 | 364 | nestedSchema := openapi3.NewSchema() 365 | nestedSchema.Properties = map[string]*openapi3.SchemaRef{ 366 | "foo": { 367 | Value: openapi3.NewStringSchema(), 368 | }, 369 | "nested": { 370 | Value: schema, 371 | }, 372 | } 373 | responseNested := openapi3.NewResponse().WithJSONSchema(nestedSchema) 374 | nestedAnyOfOperation := NewOperation() 375 | nestedAnyOfOperation.AddResponse(200, responseNested) 376 | 377 | _, err = router.AddRawRoute(http.MethodGet, "/nested-schema", okHandler, nestedAnyOfOperation) 378 | require.NoError(t, err) 379 | }, 380 | fixturesPath: "testdata/anyof.json", 381 | }, 382 | { 383 | name: "oneOf and enum are supported on properties", 384 | routes: func(t *testing.T, router *TestRouter) { 385 | _, err := router.AddRoute(http.MethodPost, "/user-profile", okHandler, Definitions{ 386 | RequestBody: &ContentValue{ 387 | Content: Content{ 388 | "application/json": { 389 | Value: &UserProfileRequest{}, 390 | }, 391 | }, 392 | }, 393 | Responses: map[int]ContentValue{ 394 | 200: { 395 | Content: Content{ 396 | "text/plain": {Value: ""}, 397 | }, 398 | }, 399 | }, 400 | }) 401 | require.NoError(t, err) 402 | 403 | schema := openapi3.NewOneOfSchema() 404 | schema.OneOf = []*openapi3.SchemaRef{ 405 | { 406 | Value: openapi3.NewFloat64Schema(). 407 | WithMin(1). 408 | WithMax(2), 409 | }, 410 | { 411 | Value: openapi3.NewFloat64Schema(). 412 | WithMin(2). 413 | WithMax(3), 414 | }, 415 | } 416 | request := openapi3.NewRequestBody().WithJSONSchema(schema) 417 | response := openapi3.NewResponse().WithJSONSchema(schema) 418 | 419 | allOperation := NewOperation() 420 | allOperation.AddResponse(200, response) 421 | allOperation.AddRequestBody(request) 422 | 423 | _, err = router.AddRawRoute(http.MethodPost, "/one-of", okHandler, allOperation) 424 | require.NoError(t, err) 425 | }, 426 | testPath: "/user-profile", 427 | testMethod: http.MethodPost, 428 | fixturesPath: "testdata/oneOf.json", 429 | }, 430 | { 431 | name: "schema with tags", 432 | routes: func(t *testing.T, router *TestRouter) { 433 | _, err := router.AddRoute(http.MethodGet, "/users", okHandler, Definitions{ 434 | Tags: []string{"Tag1", "Tag2"}, 435 | }) 436 | require.NoError(t, err) 437 | }, 438 | testPath: "/users", 439 | fixturesPath: "testdata/tags.json", 440 | }, 441 | { 442 | name: "schema with security", 443 | routes: func(t *testing.T, router *TestRouter) { 444 | _, err := router.AddRoute(http.MethodGet, "/users", okHandler, Definitions{ 445 | Security: SecurityRequirements{ 446 | SecurityRequirement{ 447 | "api_key": []string{}, 448 | "auth": []string{ 449 | "resource.write", 450 | }, 451 | }, 452 | }, 453 | }) 454 | require.NoError(t, err) 455 | }, 456 | testPath: "/users", 457 | fixturesPath: "testdata/security.json", 458 | }, 459 | { 460 | name: "schema with extension", 461 | routes: func(t *testing.T, router *TestRouter) { 462 | _, err := router.AddRoute(http.MethodGet, "/users", okHandler, Definitions{ 463 | Extensions: map[string]interface{}{ 464 | "x-extension-field": map[string]string{ 465 | "foo": "bar", 466 | }, 467 | }, 468 | }) 469 | require.NoError(t, err) 470 | }, 471 | testPath: "/users", 472 | fixturesPath: "testdata/extension.json", 473 | }, 474 | { 475 | name: "invalid extension - not starts with x-", 476 | routes: func(t *testing.T, router *TestRouter) { 477 | _, err := router.AddRoute(http.MethodGet, "/", okHandler, Definitions{ 478 | Extensions: map[string]interface{}{ 479 | "extension-field": map[string]string{ 480 | "foo": "bar", 481 | }, 482 | }, 483 | }) 484 | require.EqualError(t, err, "extra sibling fields: [extension-field]") 485 | }, 486 | fixturesPath: "testdata/empty.json", 487 | }, 488 | { 489 | name: "schema with summary, description, deprecated and operationID", 490 | routes: func(t *testing.T, router *TestRouter) { 491 | _, err := router.AddRoute(http.MethodGet, "/users", okHandler, Definitions{ 492 | Summary: "small description", 493 | Description: "this is the long route description", 494 | Deprecated: true, 495 | }) 496 | require.NoError(t, err) 497 | }, 498 | testPath: "/users", 499 | fixturesPath: "testdata/users-deprecated-with-description.json", 500 | }, 501 | } 502 | 503 | for _, test := range tests { 504 | t.Run(test.name, func(t *testing.T) { 505 | context := context.Background() 506 | r := mux.NewRouter() 507 | 508 | router, err := NewRouter(gorilla.NewRouter(r), Options{ 509 | Context: context, 510 | Openapi: getBaseSwagger(t), 511 | }) 512 | require.NoError(t, err) 513 | require.NotNil(t, router) 514 | 515 | // Add routes to test 516 | test.routes(t, router) 517 | 518 | err = router.GenerateAndExposeOpenapi() 519 | require.NoError(t, err) 520 | 521 | if test.testPath != "" { 522 | if test.testMethod == "" { 523 | test.testMethod = http.MethodGet 524 | } 525 | 526 | w := httptest.NewRecorder() 527 | req := httptest.NewRequest(test.testMethod, test.testPath, nil) 528 | r.ServeHTTP(w, req) 529 | 530 | require.Equal(t, http.StatusOK, w.Result().StatusCode) 531 | 532 | body := readBody(t, w.Result().Body) 533 | require.Equal(t, "OK", body) 534 | } 535 | 536 | t.Run("and generate openapi documentation in json", func(t *testing.T) { 537 | w := httptest.NewRecorder() 538 | req := httptest.NewRequest(http.MethodGet, DefaultJSONDocumentationPath, nil) 539 | 540 | r.ServeHTTP(w, req) 541 | 542 | require.Equal(t, http.StatusOK, w.Result().StatusCode) 543 | 544 | body := readBody(t, w.Result().Body) 545 | expected, err := os.ReadFile(test.fixturesPath) 546 | require.NoError(t, err) 547 | require.JSONEq(t, string(expected), body, "actual json data: %s", body) 548 | }) 549 | }) 550 | } 551 | } 552 | 553 | func TestResolveRequestBodySchema(t *testing.T) { 554 | type TestStruct struct { 555 | ID string `json:"id,omitempty"` 556 | } 557 | tests := []struct { 558 | name string 559 | bodySchema *ContentValue 560 | expectedErr error 561 | expectedJSON string 562 | }{ 563 | { 564 | name: "empty body schema", 565 | expectedErr: nil, 566 | expectedJSON: `{"responses": null}`, 567 | }, 568 | { 569 | name: "schema multipart", 570 | expectedErr: nil, 571 | bodySchema: &ContentValue{ 572 | Content: Content{ 573 | formDataType: { 574 | Value: &TestStruct{}, 575 | }, 576 | }, 577 | }, 578 | expectedJSON: `{ 579 | "requestBody": { 580 | "content": { 581 | "multipart/form-data": { 582 | "schema": { 583 | "type":"object", 584 | "additionalProperties":false, 585 | "properties": { 586 | "id": {"type":"string"} 587 | } 588 | } 589 | } 590 | } 591 | }, 592 | "responses": null 593 | }`, 594 | }, 595 | { 596 | name: "content-type application/json", 597 | expectedErr: nil, 598 | bodySchema: &ContentValue{ 599 | Content: Content{ 600 | jsonType: {Value: &TestStruct{}}, 601 | }, 602 | }, 603 | expectedJSON: `{ 604 | "requestBody": { 605 | "content": { 606 | "application/json": { 607 | "schema": { 608 | "type":"object", 609 | "additionalProperties":false, 610 | "properties": { 611 | "id": {"type":"string"} 612 | } 613 | } 614 | } 615 | } 616 | }, 617 | "responses": null 618 | }`, 619 | }, 620 | { 621 | name: "with description", 622 | expectedErr: nil, 623 | bodySchema: &ContentValue{ 624 | Content: Content{ 625 | jsonType: { 626 | Value: &TestStruct{}, 627 | }, 628 | }, 629 | Description: "my custom description", 630 | }, 631 | expectedJSON: `{ 632 | "requestBody": { 633 | "description": "my custom description", 634 | "content": { 635 | "application/json": { 636 | "schema": { 637 | "type":"object", 638 | "additionalProperties":false, 639 | "properties": { 640 | "id": {"type":"string"} 641 | } 642 | } 643 | } 644 | } 645 | }, 646 | "responses": null 647 | }`, 648 | }, 649 | { 650 | name: "content type text/plain", 651 | bodySchema: &ContentValue{ 652 | Content: Content{ 653 | "text/plain": {Value: ""}, 654 | }, 655 | }, 656 | expectedJSON: `{ 657 | "requestBody": { 658 | "content": { 659 | "text/plain": { 660 | "schema": { 661 | "type":"string" 662 | } 663 | } 664 | } 665 | }, 666 | "responses": null 667 | }`, 668 | }, 669 | { 670 | name: "generic content type - it represent all types", 671 | bodySchema: &ContentValue{ 672 | Content: Content{ 673 | "*/*": { 674 | Value: &TestStruct{}, 675 | AllowAdditionalProperties: true, 676 | }, 677 | }, 678 | }, 679 | expectedJSON: `{ 680 | "requestBody": { 681 | "content": { 682 | "*/*": { 683 | "schema": { 684 | "type":"object", 685 | "properties": { 686 | "id": {"type": "string"} 687 | } 688 | } 689 | } 690 | } 691 | }, 692 | "responses": null 693 | }`, 694 | }, 695 | } 696 | 697 | mux := mux.NewRouter() 698 | router, err := NewRouter(gorilla.NewRouter(mux), Options{ 699 | Openapi: getBaseSwagger(t), 700 | }) 701 | require.NoError(t, err) 702 | 703 | for _, test := range tests { 704 | t.Run(test.name, func(t *testing.T) { 705 | operation := NewOperation() 706 | 707 | err := router.resolveRequestBodySchema(test.bodySchema, operation) 708 | 709 | if err == nil { 710 | data, _ := operation.MarshalJSON() 711 | jsonData := string(data) 712 | require.JSONEq(t, test.expectedJSON, jsonData, "actual json data: %s", jsonData) 713 | require.NoError(t, err) 714 | } 715 | require.Equal(t, test.expectedErr, err) 716 | }) 717 | } 718 | } 719 | 720 | func TestResolveResponsesSchema(t *testing.T) { 721 | type TestStruct struct { 722 | Message string `json:"message,omitempty"` 723 | } 724 | type NestedTestStruct struct { 725 | Notification string `json:"notification"` 726 | NestedMapOfStructs map[string]TestStruct `json:"nestedMapOfStructs,omitempty"` 727 | } 728 | type ComplexTestStruct struct { 729 | Communication string `json:"communication"` 730 | MapOfStructs map[string]NestedTestStruct `json:"mapOfStructs,omitempty"` 731 | } 732 | tests := []struct { 733 | name string 734 | responsesSchema map[int]ContentValue 735 | expectedErr error 736 | expectedJSON string 737 | }{ 738 | { 739 | name: "empty responses schema", 740 | expectedErr: nil, 741 | expectedJSON: `{"responses": {"default":{"description":""}}}`, 742 | }, 743 | { 744 | name: "with 1 status code", 745 | responsesSchema: map[int]ContentValue{ 746 | 200: { 747 | Content: Content{ 748 | jsonType: {Value: &TestStruct{}}, 749 | }, 750 | }, 751 | }, 752 | expectedErr: nil, 753 | expectedJSON: `{ 754 | "responses": { 755 | "200": { 756 | "description": "", 757 | "content": { 758 | "application/json": { 759 | "schema": { 760 | "type": "object", 761 | "properties": { 762 | "message": { 763 | "type": "string" 764 | } 765 | }, 766 | "additionalProperties": false 767 | } 768 | } 769 | } 770 | } 771 | } 772 | }`, 773 | }, 774 | { 775 | name: "with complex schema", 776 | responsesSchema: map[int]ContentValue{ 777 | 200: { 778 | Content: Content{ 779 | jsonType: {Value: &ComplexTestStruct{ 780 | Communication: "myCommunication", 781 | MapOfStructs: map[string]NestedTestStruct{ 782 | "myProperty": { 783 | Notification: "myNotification", 784 | NestedMapOfStructs: map[string]TestStruct{ 785 | "myNestedProperty": { 786 | Message: "myMessage", 787 | }, 788 | }, 789 | }, 790 | }, 791 | }}, 792 | }, 793 | }, 794 | }, 795 | expectedErr: nil, 796 | expectedJSON: `{ 797 | "responses": { 798 | "200": { 799 | "content": { 800 | "application/json": { 801 | "schema": { 802 | "additionalProperties": false, 803 | "properties": { 804 | "communication": { 805 | "type": "string" 806 | }, 807 | "mapOfStructs": { 808 | "additionalProperties": { 809 | "additionalProperties": false, 810 | "properties": { 811 | "nestedMapOfStructs": { 812 | "additionalProperties": { 813 | "additionalProperties": false, 814 | "properties": { 815 | "message": { 816 | "type": "string" 817 | } 818 | }, 819 | "type": "object" 820 | }, 821 | "type": "object" 822 | }, 823 | "notification": { 824 | "type": "string" 825 | } 826 | }, 827 | "required": [ 828 | "notification" 829 | ], 830 | "type": "object" 831 | }, 832 | "type": "object" 833 | } 834 | }, 835 | "required": [ 836 | "communication" 837 | ], 838 | "type": "object" 839 | } 840 | } 841 | }, 842 | "description": "" 843 | } 844 | } 845 | }`, 846 | }, 847 | { 848 | name: "with more status codes", 849 | responsesSchema: map[int]ContentValue{ 850 | 200: { 851 | Content: Content{ 852 | jsonType: {Value: &TestStruct{}}, 853 | }, 854 | }, 855 | 400: { 856 | Content: Content{ 857 | jsonType: {Value: ""}, 858 | }, 859 | }, 860 | }, 861 | expectedErr: nil, 862 | expectedJSON: `{ 863 | "responses": { 864 | "200": { 865 | "description": "", 866 | "content": { 867 | "application/json": { 868 | "schema": { 869 | "type": "object", 870 | "properties": { 871 | "message": { 872 | "type": "string" 873 | } 874 | }, 875 | "additionalProperties": false 876 | } 877 | } 878 | } 879 | }, 880 | "400": { 881 | "description": "", 882 | "content": { 883 | "application/json": { 884 | "schema": { 885 | "type": "string" 886 | } 887 | } 888 | } 889 | } 890 | } 891 | }`, 892 | }, 893 | { 894 | name: "with custom description", 895 | responsesSchema: map[int]ContentValue{ 896 | 400: { 897 | Content: Content{ 898 | jsonType: {Value: ""}, 899 | }, 900 | Description: "a description", 901 | }, 902 | }, 903 | expectedErr: nil, 904 | expectedJSON: `{ 905 | "responses": { 906 | "400": { 907 | "description": "a description", 908 | "content": { 909 | "application/json": { 910 | "schema": { 911 | "type": "string" 912 | } 913 | } 914 | } 915 | } 916 | } 917 | }`, 918 | }, 919 | } 920 | 921 | mux := mux.NewRouter() 922 | router, err := NewRouter(gorilla.NewRouter(mux), Options{ 923 | Openapi: getBaseSwagger(t), 924 | }) 925 | require.NoError(t, err) 926 | 927 | for _, test := range tests { 928 | t.Run(test.name, func(t *testing.T) { 929 | operation := NewOperation() 930 | operation.Responses = &openapi3.Responses{} 931 | 932 | err := router.resolveResponsesSchema(test.responsesSchema, operation) 933 | 934 | if err == nil { 935 | data, _ := operation.MarshalJSON() 936 | jsonData := string(data) 937 | require.JSONEq(t, test.expectedJSON, jsonData, "actual json data: %s", jsonData) 938 | require.NoError(t, err) 939 | } 940 | require.Equal(t, test.expectedErr, err) 941 | }) 942 | } 943 | } 944 | 945 | func TestResolveParametersSchema(t *testing.T) { 946 | type TestStruct struct { 947 | Message string `json:"message,omitempty"` 948 | } 949 | tests := []struct { 950 | name string 951 | paramsSchema ParameterValue 952 | paramType string 953 | expectedErr error 954 | expectedJSON string 955 | }{ 956 | { 957 | name: "empty responses schema", 958 | paramType: pathParamsType, 959 | expectedJSON: `{"responses": null}`, 960 | }, 961 | { 962 | name: "path param", 963 | paramType: pathParamsType, 964 | paramsSchema: ParameterValue{ 965 | "foo": { 966 | Schema: &Schema{ 967 | Value: "", 968 | }, 969 | }, 970 | }, 971 | expectedJSON: `{ 972 | "parameters": [{ 973 | "in": "path", 974 | "name": "foo", 975 | "required": true, 976 | "schema": { 977 | "type": "string" 978 | } 979 | }], 980 | "responses": null 981 | }`, 982 | }, 983 | { 984 | name: "query param", 985 | paramType: queryParamType, 986 | paramsSchema: ParameterValue{ 987 | "foo": { 988 | Schema: &Schema{ 989 | Value: "", 990 | }, 991 | }, 992 | }, 993 | expectedJSON: `{ 994 | "parameters": [{ 995 | "in": "query", 996 | "name": "foo", 997 | "schema": { 998 | "type": "string" 999 | } 1000 | }], 1001 | "responses": null 1002 | }`, 1003 | }, 1004 | { 1005 | name: "cookie param", 1006 | paramType: cookieParamType, 1007 | paramsSchema: ParameterValue{ 1008 | "foo": { 1009 | Schema: &Schema{ 1010 | Value: "", 1011 | }, 1012 | }, 1013 | }, 1014 | expectedJSON: `{ 1015 | "parameters": [{ 1016 | "in": "cookie", 1017 | "name": "foo", 1018 | "schema": { 1019 | "type": "string" 1020 | } 1021 | }], 1022 | "responses": null 1023 | }`, 1024 | }, 1025 | { 1026 | name: "header param", 1027 | paramType: headerParamType, 1028 | paramsSchema: ParameterValue{ 1029 | "foo": { 1030 | Schema: &Schema{ 1031 | Value: "", 1032 | }, 1033 | }, 1034 | }, 1035 | expectedJSON: `{ 1036 | "parameters": [{ 1037 | "in": "header", 1038 | "name": "foo", 1039 | "schema": { 1040 | "type": "string" 1041 | } 1042 | }], 1043 | "responses": null 1044 | }`, 1045 | }, 1046 | { 1047 | name: "wrong param type", 1048 | paramType: "wrong", 1049 | paramsSchema: ParameterValue{ 1050 | "foo": { 1051 | Schema: &Schema{ 1052 | Value: "", 1053 | }, 1054 | }, 1055 | }, 1056 | expectedErr: fmt.Errorf("invalid param type"), 1057 | }, 1058 | { 1059 | name: "content param", 1060 | paramType: "query", 1061 | paramsSchema: ParameterValue{ 1062 | "foo": { 1063 | Content: Content{ 1064 | jsonType: { 1065 | Value: &TestStruct{}, 1066 | }, 1067 | }, 1068 | }, 1069 | }, 1070 | expectedJSON: `{ 1071 | "parameters": [{ 1072 | "in": "query", 1073 | "name": "foo", 1074 | "content": { 1075 | "application/json": { 1076 | "schema": { 1077 | "type": "object", 1078 | "properties": { 1079 | "message": {"type": "string"} 1080 | }, 1081 | "additionalProperties": false 1082 | } 1083 | } 1084 | } 1085 | }], 1086 | "responses": null 1087 | }`, 1088 | }, 1089 | } 1090 | 1091 | mux := mux.NewRouter() 1092 | router, err := NewRouter(gorilla.NewRouter(mux), Options{ 1093 | Openapi: getBaseSwagger(t), 1094 | }) 1095 | require.NoError(t, err) 1096 | 1097 | for _, test := range tests { 1098 | t.Run(test.name, func(t *testing.T) { 1099 | operation := NewOperation() 1100 | 1101 | err := router.resolveParameterSchema(test.paramType, test.paramsSchema, operation) 1102 | 1103 | if err == nil { 1104 | data, _ := operation.MarshalJSON() 1105 | jsonData := string(data) 1106 | require.JSONEq(t, test.expectedJSON, jsonData, "actual json data: %s", jsonData) 1107 | require.NoError(t, err) 1108 | } 1109 | require.Equal(t, test.expectedErr, err) 1110 | }) 1111 | } 1112 | } 1113 | 1114 | func getBaseSwagger(t *testing.T) *openapi3.T { 1115 | t.Helper() 1116 | 1117 | return &openapi3.T{ 1118 | Info: &openapi3.Info{ 1119 | Title: "test openapi title", 1120 | Version: "test openapi version", 1121 | }, 1122 | } 1123 | } 1124 | 1125 | func TestGetPathParamsAutoComplete(t *testing.T) { 1126 | testCases := map[string]struct { 1127 | schemaDefinition Definitions 1128 | path string 1129 | expected ParameterValue 1130 | }{ 1131 | "no path params": { 1132 | schemaDefinition: Definitions{}, 1133 | path: "/users", 1134 | expected: nil, 1135 | }, 1136 | "with path params": { 1137 | schemaDefinition: Definitions{}, 1138 | path: "/users/{userId}", 1139 | expected: ParameterValue{ 1140 | "userId": { 1141 | Schema: &Schema{Value: ""}, 1142 | }, 1143 | }, 1144 | }, 1145 | "with multiple path params": { 1146 | schemaDefinition: Definitions{}, 1147 | path: "/foo/{bar}.{taz}", 1148 | expected: ParameterValue{ 1149 | "bar": { 1150 | Schema: &Schema{Value: ""}, 1151 | }, 1152 | "taz": { 1153 | Schema: &Schema{Value: ""}, 1154 | }, 1155 | }, 1156 | }, 1157 | "with nested multiple path params": { 1158 | schemaDefinition: Definitions{}, 1159 | path: "/foo/{bar}.{taz}/{baz}/ok", 1160 | expected: ParameterValue{ 1161 | "bar": { 1162 | Schema: &Schema{Value: ""}, 1163 | }, 1164 | "taz": { 1165 | Schema: &Schema{Value: ""}, 1166 | }, 1167 | "baz": { 1168 | Schema: &Schema{Value: ""}, 1169 | }, 1170 | }, 1171 | }, 1172 | } 1173 | 1174 | for name, test := range testCases { 1175 | t.Run(name, func(t *testing.T) { 1176 | actual := getPathParamsAutoComplete(test.schemaDefinition, test.path) 1177 | 1178 | require.Equal(t, test.expected, actual) 1179 | }) 1180 | } 1181 | } 1182 | --------------------------------------------------------------------------------