-
Notifications
You must be signed in to change notification settings - Fork 153
[Feature] scalar alternative to swagger ui #1283
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Closed
Closed
Changes from 2 commits
Commits
Show all changes
14 commits
Select commit
Hold shift + click to select a range
9a06f36
add core logic
yokeTH 09b202b
Add Scalar middleware documentation with README
yokeTH 063a95f
Update Go version requirement and clean up dependencies
yokeTH 8658b33
Follow the change request
yokeTH 211c73d
rename swagger to scalar and open api
yokeTH 3bf792d
bring cache back
yokeTH 0e3bff6
handle fill potential missing file
yokeTH 5d916ed
Update README.md
yokeTH 4694c45
Refactor error handling and request path checks
yokeTH 9616299
Add Swagger documentation and tests
yokeTH 63b258d
Merge branch 'main' into main
yokeTH 4ecfb54
no longer directly read fromfile
yokeTH d6e6ab2
Merge branch 'gofiber:main' into main
yokeTH ecc461f
feat: integrate with my current version
yokeTH File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,129 @@ | ||
| --- | ||
| id: scalar | ||
| title: Scalar | ||
| --- | ||
|
|
||
| # Scalar | ||
|
|
||
| Scalar middleware for [Fiber](https://github.com/gofiber/fiber). The middleware handles Scalar UI. | ||
|
|
||
| **Note: Requires Go 1.24.2 and above** | ||
yokeTH marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
|
|
||
| ### Table of Contents | ||
| - [Signatures](#signatures) | ||
| - [Installation](#installation) | ||
| - [Examples](#examples) | ||
| - [Config](#config) | ||
| - [Default Config](#default-config) | ||
|
|
||
| ### Signatures | ||
| ```go | ||
| func New(config ...scalar.Config) fiber.Handler | ||
| ``` | ||
|
|
||
| ### Installation | ||
| Scalar is tested on the latest [Go versions](https://golang.org/dl/) with support for modules. So make sure to initialize one first if you didn't do that yet: | ||
| ```bash | ||
| go mod init github.com/<user>/<repo> | ||
| ``` | ||
| And then install the Scalar middleware: | ||
| ```bash | ||
| go get github.com/gofiber/contrib/scalar | ||
| ``` | ||
|
|
||
| ### Examples | ||
| Import the middleware package | ||
| ```go | ||
| import ( | ||
| "github.com/gofiber/fiber/v2" | ||
| "github.com/gofiber/contrib/scalar" | ||
| ) | ||
| ``` | ||
|
|
||
| Using swaggo to generate documents default output path is `(root)/docs`: | ||
| ```bash | ||
| swag init -v3.1 | ||
| ``` | ||
|
|
||
| Using the default config: | ||
| ```go | ||
| app.Use(scalar.New()) | ||
| ``` | ||
|
|
||
| Using a custom config: | ||
| ```go | ||
| cfg := scalar.Config{ | ||
| BasePath: "/", | ||
| FilePath: "./docs/swagger.json", | ||
| Path: "swagger", | ||
| Title: "Swagger API Docs", | ||
| } | ||
|
|
||
| app.Use(scalar.New(cfg)) | ||
| ``` | ||
|
|
||
| Use program data for Swagger content: | ||
| ```go | ||
| cfg := scalar.Config{ | ||
| BasePath: "/", | ||
| FilePath: "./docs/swagger.json", | ||
| FileContent: mySwaggerByteSlice, | ||
| Path: "swagger", | ||
| Title: "Swagger API Docs", | ||
| } | ||
|
|
||
| app.Use(scalar.New(cfg)) | ||
| ``` | ||
|
|
||
| ### Config | ||
| ```go | ||
| type Config struct { | ||
| // Next defines a function to skip this middleware when returned true. | ||
| // | ||
| // Optional. Default: nil | ||
| Next func(c *fiber.Ctx) bool | ||
|
|
||
| // BasePath for the UI path | ||
| // | ||
| // Optional. Default: / | ||
| BasePath string | ||
|
|
||
| // FilePath for the swagger.json or swagger.yaml file | ||
| // | ||
| // Optional. Default: ./docs/swagger.json | ||
| FilePath string | ||
|
|
||
| // FileContent for the content of the swagger.json or swagger.yaml file. | ||
| // If provided, FilePath will not be read. | ||
| // | ||
| // Optional. Default: nil | ||
| FileContent []byte | ||
|
|
||
| // Path combines with BasePath for the full UI path | ||
| // | ||
| // Optional. Default: docs | ||
| Path string | ||
|
|
||
| // Title for the documentation site | ||
| // | ||
| // Optional. Default: Fiber API documentation | ||
| Title string | ||
|
|
||
| // CacheAge defines the max-age for the Cache-Control header in seconds. | ||
| // | ||
| // Optional. Default: 0 (no cache) | ||
| CacheAge int | ||
| } | ||
yokeTH marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
| ``` | ||
|
|
||
| ### Default Config | ||
| ```go | ||
| var ConfigDefault = Config{ | ||
| Next: nil, | ||
| BasePath: "/", | ||
| FilePath: "./docs/swagger.json", | ||
| Path: "docs", | ||
| Title: "Fiber API documentation", | ||
| CacheAge: 0, | ||
| } | ||
yokeTH marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
| ``` | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,37 @@ | ||
| module github.com/gofiber/contrib/scalar | ||
|
|
||
| go 1.24.2 | ||
yokeTH marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
|
|
||
| require ( | ||
| github.com/andybalholm/brotli v1.1.0 // indirect | ||
| github.com/asaskevich/govalidator v0.0.0-20230301143203-a9d515a09cc2 // indirect | ||
| github.com/go-openapi/analysis v0.23.0 // indirect | ||
| github.com/go-openapi/errors v0.22.0 // indirect | ||
| github.com/go-openapi/jsonpointer v0.21.0 // indirect | ||
| github.com/go-openapi/jsonreference v0.21.0 // indirect | ||
| github.com/go-openapi/loads v0.22.0 // indirect | ||
| github.com/go-openapi/runtime v0.28.0 // indirect | ||
| github.com/go-openapi/spec v0.21.0 // indirect | ||
| github.com/go-openapi/strfmt v0.23.0 // indirect | ||
| github.com/go-openapi/swag v0.23.0 // indirect | ||
| github.com/go-openapi/validate v0.24.0 // indirect | ||
| github.com/gofiber/fiber/v2 v2.52.6 // indirect | ||
| github.com/google/uuid v1.6.0 // indirect | ||
| github.com/josharian/intern v1.0.0 // indirect | ||
| github.com/klauspost/compress v1.17.9 // indirect | ||
| github.com/mailru/easyjson v0.7.7 // indirect | ||
| github.com/mattn/go-colorable v0.1.13 // indirect | ||
| github.com/mattn/go-isatty v0.0.20 // indirect | ||
| github.com/mattn/go-runewidth v0.0.16 // indirect | ||
| github.com/mitchellh/mapstructure v1.5.0 // indirect | ||
| github.com/oklog/ulid v1.3.1 // indirect | ||
| github.com/rivo/uniseg v0.2.0 // indirect | ||
| github.com/valyala/bytebufferpool v1.0.0 // indirect | ||
| github.com/valyala/fasthttp v1.51.0 // indirect | ||
| github.com/valyala/tcplisten v1.0.0 // indirect | ||
| go.mongodb.org/mongo-driver v1.14.0 // indirect | ||
| golang.org/x/sync v0.6.0 // indirect | ||
| golang.org/x/sys v0.28.0 // indirect | ||
| gopkg.in/yaml.v2 v2.4.0 // indirect | ||
| gopkg.in/yaml.v3 v3.0.1 // indirect | ||
| ) | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,66 @@ | ||
| github.com/andybalholm/brotli v1.1.0 h1:eLKJA0d02Lf0mVpIDgYnqXcUn0GqVmEFny3VuID1U3M= | ||
| github.com/andybalholm/brotli v1.1.0/go.mod h1:sms7XGricyQI9K10gOSf56VKKWS4oLer58Q+mhRPtnY= | ||
| github.com/asaskevich/govalidator v0.0.0-20230301143203-a9d515a09cc2 h1:DklsrG3dyBCFEj5IhUbnKptjxatkF07cF2ak3yi77so= | ||
| github.com/asaskevich/govalidator v0.0.0-20230301143203-a9d515a09cc2/go.mod h1:WaHUgvxTVq04UNunO+XhnAqY/wQc+bxr74GqbsZ/Jqw= | ||
| github.com/go-openapi/analysis v0.23.0 h1:aGday7OWupfMs+LbmLZG4k0MYXIANxcuBTYUC03zFCU= | ||
| github.com/go-openapi/analysis v0.23.0/go.mod h1:9mz9ZWaSlV8TvjQHLl2mUW2PbZtemkE8yA5v22ohupo= | ||
| github.com/go-openapi/errors v0.22.0 h1:c4xY/OLxUBSTiepAg3j/MHuAv5mJhnf53LLMWFB+u/w= | ||
| github.com/go-openapi/errors v0.22.0/go.mod h1:J3DmZScxCDufmIMsdOuDHxJbdOGC0xtUynjIx092vXE= | ||
| github.com/go-openapi/jsonpointer v0.21.0 h1:YgdVicSA9vH5RiHs9TZW5oyafXZFc6+2Vc1rr/O9oNQ= | ||
| github.com/go-openapi/jsonpointer v0.21.0/go.mod h1:IUyH9l/+uyhIYQ/PXVA41Rexl+kOkAPDdXEYns6fzUY= | ||
| github.com/go-openapi/jsonreference v0.21.0 h1:Rs+Y7hSXT83Jacb7kFyjn4ijOuVGSvOdF2+tg1TRrwQ= | ||
| github.com/go-openapi/jsonreference v0.21.0/go.mod h1:LmZmgsrTkVg9LG4EaHeY8cBDslNPMo06cago5JNLkm4= | ||
| github.com/go-openapi/loads v0.22.0 h1:ECPGd4jX1U6NApCGG1We+uEozOAvXvJSF4nnwHZ8Aco= | ||
| github.com/go-openapi/loads v0.22.0/go.mod h1:yLsaTCS92mnSAZX5WWoxszLj0u+Ojl+Zs5Stn1oF+rs= | ||
| github.com/go-openapi/runtime v0.28.0 h1:gpPPmWSNGo214l6n8hzdXYhPuJcGtziTOgUpvsFWGIQ= | ||
| github.com/go-openapi/runtime v0.28.0/go.mod h1:QN7OzcS+XuYmkQLw05akXk0jRH/eZ3kb18+1KwW9gyc= | ||
| github.com/go-openapi/spec v0.21.0 h1:LTVzPc3p/RzRnkQqLRndbAzjY0d0BCL72A6j3CdL9ZY= | ||
| github.com/go-openapi/spec v0.21.0/go.mod h1:78u6VdPw81XU44qEWGhtr982gJ5BWg2c0I5XwVMotYk= | ||
| github.com/go-openapi/strfmt v0.23.0 h1:nlUS6BCqcnAk0pyhi9Y+kdDVZdZMHfEKQiS4HaMgO/c= | ||
| github.com/go-openapi/strfmt v0.23.0/go.mod h1:NrtIpfKtWIygRkKVsxh7XQMDQW5HKQl6S5ik2elW+K4= | ||
| github.com/go-openapi/swag v0.23.0 h1:vsEVJDUo2hPJ2tu0/Xc+4noaxyEffXNIs3cOULZ+GrE= | ||
| github.com/go-openapi/swag v0.23.0/go.mod h1:esZ8ITTYEsH1V2trKHjAN8Ai7xHb8RV+YSZ577vPjgQ= | ||
| github.com/go-openapi/validate v0.24.0 h1:LdfDKwNbpB6Vn40xhTdNZAnfLECL81w+VX3BumrGD58= | ||
| github.com/go-openapi/validate v0.24.0/go.mod h1:iyeX1sEufmv3nPbBdX3ieNviWnOZaJ1+zquzJEf2BAQ= | ||
| github.com/gofiber/fiber/v2 v2.52.6 h1:Rfp+ILPiYSvvVuIPvxrBns+HJp8qGLDnLJawAu27XVI= | ||
| github.com/gofiber/fiber/v2 v2.52.6/go.mod h1:YEcBbO/FB+5M1IZNBP9FO3J9281zgPAreiI1oqg8nDw= | ||
| github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0= | ||
| github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo= | ||
| github.com/josharian/intern v1.0.0 h1:vlS4z54oSdjm0bgjRigI+G1HpF+tI+9rE5LLzOg8HmY= | ||
| github.com/josharian/intern v1.0.0/go.mod h1:5DoeVV0s6jJacbCEi61lwdGj/aVlrQvzHFFd8Hwg//Y= | ||
| github.com/klauspost/compress v1.17.9 h1:6KIumPrER1LHsvBVuDa0r5xaG0Es51mhhB9BQB2qeMA= | ||
| github.com/klauspost/compress v1.17.9/go.mod h1:Di0epgTjJY877eYKx5yC51cX2A2Vl2ibi7bDH9ttBbw= | ||
| github.com/mailru/easyjson v0.7.7 h1:UGYAvKxe3sBsEDzO8ZeWOSlIQfWFlxbzLZe7hwFURr0= | ||
| github.com/mailru/easyjson v0.7.7/go.mod h1:xzfreul335JAWq5oZzymOObrkdz5UnU4kGfJJLY9Nlc= | ||
| github.com/mattn/go-colorable v0.1.13 h1:fFA4WZxdEF4tXPZVKMLwD8oUnCTTo08duU7wxecdEvA= | ||
| github.com/mattn/go-colorable v0.1.13/go.mod h1:7S9/ev0klgBDR4GtXTXX8a3vIGJpMovkB8vQcUbaXHg= | ||
| github.com/mattn/go-isatty v0.0.16/go.mod h1:kYGgaQfpe5nmfYZH+SKPsOc2e4SrIfOl2e/yFXSvRLM= | ||
| github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY= | ||
| github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y= | ||
| github.com/mattn/go-runewidth v0.0.16 h1:E5ScNMtiwvlvB5paMFdw9p4kSQzbXFikJ5SQO6TULQc= | ||
| github.com/mattn/go-runewidth v0.0.16/go.mod h1:Jdepj2loyihRzMpdS35Xk/zdY8IAYHsh153qUoGf23w= | ||
| github.com/mitchellh/mapstructure v1.5.0 h1:jeMsZIYE/09sWLaz43PL7Gy6RuMjD2eJVyuac5Z2hdY= | ||
| github.com/mitchellh/mapstructure v1.5.0/go.mod h1:bFUtVrKA4DC2yAKiSyO/QUcy7e+RRV2QTWOzhPopBRo= | ||
| github.com/oklog/ulid v1.3.1 h1:EGfNDEx6MqHz8B3uNV6QAib1UR2Lm97sHi3ocA6ESJ4= | ||
| github.com/oklog/ulid v1.3.1/go.mod h1:CirwcVhetQ6Lv90oh/F+FBtV6XMibvdAFo93nm5qn4U= | ||
| github.com/rivo/uniseg v0.2.0 h1:S1pD9weZBuJdFmowNwbpi7BJ8TNftyUImj/0WQi72jY= | ||
| github.com/rivo/uniseg v0.2.0/go.mod h1:J6wj4VEh+S6ZtnVlnTBMWIodfgj8LQOQFoIToxlJtxc= | ||
| github.com/valyala/bytebufferpool v1.0.0 h1:GqA5TC/0021Y/b9FG4Oi9Mr3q7XYx6KllzawFIhcdPw= | ||
| github.com/valyala/bytebufferpool v1.0.0/go.mod h1:6bBcMArwyJ5K/AmCkWv1jt77kVWyCJ6HpOuEn7z0Csc= | ||
| github.com/valyala/fasthttp v1.51.0 h1:8b30A5JlZ6C7AS81RsWjYMQmrZG6feChmgAolCl1SqA= | ||
| github.com/valyala/fasthttp v1.51.0/go.mod h1:oI2XroL+lI7vdXyYoQk03bXBThfFl2cVdIA3Xl7cH8g= | ||
| github.com/valyala/tcplisten v1.0.0 h1:rBHj/Xf+E1tRGZyWIWwJDiRY0zc1Js+CV5DqwacVSA8= | ||
| github.com/valyala/tcplisten v1.0.0/go.mod h1:T0xQ8SeCZGxckz9qRXTfG43PvQ/mcWh7FwZEA7Ioqkc= | ||
| go.mongodb.org/mongo-driver v1.14.0 h1:P98w8egYRjYe3XDjxhYJagTokP/H6HzlsnojRgZRd80= | ||
| go.mongodb.org/mongo-driver v1.14.0/go.mod h1:Vzb0Mk/pa7e6cWw85R4F/endUC3u0U9jGcNU603k65c= | ||
| golang.org/x/sync v0.6.0 h1:5BMeUDZ7vkXGfEr1x9B4bRcTH4lpkTkpdh0T/J+qjbQ= | ||
| golang.org/x/sync v0.6.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk= | ||
| golang.org/x/sys v0.0.0-20220811171246-fbc7d0a398ab/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= | ||
| golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= | ||
| golang.org/x/sys v0.28.0 h1:Fksou7UEQUWlKvIdsqzJmUmCX3cZuD2+P3XyyzwMhlA= | ||
| golang.org/x/sys v0.28.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA= | ||
| gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0= | ||
| gopkg.in/yaml.v2 v2.4.0 h1:D8xgwECY7CYvx+Y2n4sBz93Jn9JRvxdiyyo8CTfuKaY= | ||
| gopkg.in/yaml.v2 v2.4.0/go.mod h1:RDklbk79AGWmwhnvt/jBztapEOGDOx6ZbXqjP6csGnQ= | ||
| gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA= | ||
| gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM= |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
add badges
https://github.com/gofiber/contrib/blob/main/casbin/README.md?plain=1#L7-L9