Skip to content

Commit ea5a17f

Browse files
rookie-luochaorookie-luochao
committed
feat: init
0 parents  commit ea5a17f

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

48 files changed

+2624
-0
lines changed

‎.github/workflows/ci.yaml

+37
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
name: CI
2+
on:
3+
push:
4+
branches:
5+
- main
6+
pull_request:
7+
branches:
8+
- main
9+
permissions:
10+
contents: read
11+
jobs:
12+
lint:
13+
strategy:
14+
matrix:
15+
go: ['1.17','1.21']
16+
os: ['ubuntu-latest']
17+
name: lint
18+
runs-on: ${{ matrix.os }}
19+
steps:
20+
- uses: actions/setup-go@v3
21+
with:
22+
go-version: ${{ matrix.go }}
23+
- uses: actions/checkout@v3
24+
- uses: golangci/golangci-lint-action@v3
25+
test:
26+
strategy:
27+
matrix:
28+
go: ['1.17','1.21']
29+
os: ['ubuntu-latest']
30+
name: test
31+
runs-on: ${{ matrix.os }}
32+
steps:
33+
- uses: actions/setup-go@v3
34+
with:
35+
go-version: ${{ matrix.go }}
36+
- uses: actions/checkout@v3
37+
- run: go test -race ./...

‎.gitignore

+2
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
.idea
2+
.DS_Store

‎LICENSE

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2024 rookie-luochao
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.

‎Makefile

+20
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
.PHONY: all lint test deps
2+
3+
DOC_PATH=assets/openapi-ui.umd.js
4+
DOC_URL=https://cdn.jsdelivr.net/npm/openapi-ui-dist@latest/lib/openapi-ui.umd.js
5+
6+
all: $(DOC_PATH) lint test
7+
8+
lint:
9+
go fmt ./...
10+
go vet ./...
11+
golangci-lint run ./...
12+
13+
test:
14+
go test -race ./...
15+
16+
deps:
17+
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
18+
19+
$(DOC_PATH):
20+
curl -sL -o $(DOC_PATH) $(DOC_URL)

‎README.md

+91
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
# go-openapi-ui
2+
3+
`go-openapi-ui` is an embedded OpenAPI documentation ui for Go using [OpenAPI-UI](https://github.com/rookie-luochao/openapi-ui) and Go's [1.17+'s embed package](https://golang.org/pkg/embed/), with middleware implementations for: `net/http`, `gin`, `fiber`, and `echo`.
4+
5+
The template is based on the OpenAPI-UI [bundle.js](https://github.com/rookie-luochao/openapi-ui/blob/master/lib/openapi-ui.umd.js) with the script already placed in the html instead of depending on a CDN.
6+
7+
This package does not generate openapi spec file. Check [this example](_examples/gen) for using code generation with swag.
8+
9+
## Usage
10+
11+
```go
12+
import "github.com/rookie-luochao/go-openapi-ui"
13+
14+
...
15+
16+
doc := doc.Doc{
17+
Title: "Example API",
18+
Description: "Example API Description",
19+
SpecFile: "./openapi.json", // "./openapi.yaml"
20+
SpecPath: "/openapi.json", // "/openapi.yaml"
21+
DocsPath: "/docs",
22+
}
23+
```
24+
25+
- `net/http`
26+
27+
```go
28+
import (
29+
"net/http"
30+
"github.com/rookie-luochao/go-openapi-ui"
31+
)
32+
33+
...
34+
35+
http.ListenAndServe(address, doc.Handler())
36+
```
37+
38+
- `gin`
39+
40+
```go
41+
import (
42+
"github.com/gin-gonic/gin"
43+
"github.com/rookie-luochao/go-openapi-ui"
44+
ginopenapiui "github.com/rookie-luochao/go-openapi-ui/gin"
45+
)
46+
47+
...
48+
49+
r := gin.New()
50+
r.Use(ginopenapiui.New(doc))
51+
```
52+
53+
- `echo`
54+
55+
```go
56+
import (
57+
"github.com/labstack/echo/v4"
58+
"github.com/rookie-luochao/go-openapi-ui"
59+
echoopenapiui "github.com/rookie-luochao/go-openapi-ui/echo"
60+
)
61+
62+
...
63+
64+
r := echo.New()
65+
r.Use(echoopenapiui.New(doc))
66+
```
67+
68+
- `fiber`
69+
70+
```go
71+
import (
72+
"github.com/gofiber/fiber/v2"
73+
"github.com/rookie-luochao/go-openapi-ui"
74+
fiberopenapiui "github.com/rookie-luochao/go-openapi-ui/fiber"
75+
)
76+
77+
...
78+
79+
r := fiber.New()
80+
r.Use(fiberopenapiui.New(doc))
81+
```
82+
83+
See [examples](/_examples)
84+
85+
## 致谢
86+
87+
- [go-redoc](https://github.com/mvrilo/go-redoc)
88+
89+
## LICENSE
90+
91+
[MIT](LICENSE)

‎_examples/echo/go.mod

+24
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
module github.com/rookie-luochao/go-openapi-ui/_examples/echo
2+
3+
go 1.21.6
4+
5+
replace github.com/rookie-luochao/go-openapi-ui => ../../
6+
replace github.com/rookie-luochao/go-openapi-ui/echo => ../../echo
7+
8+
require (
9+
github.com/labstack/echo/v4 v4.11.4
10+
github.com/rookie-luochao/go-openapi-ui v0.0.0
11+
github.com/rookie-luochao/go-openapi-ui/echo v0.0.0
12+
)
13+
14+
require (
15+
github.com/labstack/gommon v0.4.2 // indirect
16+
github.com/mattn/go-colorable v0.1.13 // indirect
17+
github.com/mattn/go-isatty v0.0.20 // indirect
18+
github.com/valyala/bytebufferpool v1.0.0 // indirect
19+
github.com/valyala/fasttemplate v1.2.2 // indirect
20+
golang.org/x/crypto v0.22.0 // indirect
21+
golang.org/x/net v0.21.0 // indirect
22+
golang.org/x/sys v0.19.0 // indirect
23+
golang.org/x/text v0.14.0 // indirect
24+
)

‎_examples/echo/go.sum

+37
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
2+
github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
3+
github.com/labstack/echo/v4 v4.11.4 h1:vDZmA+qNeh1pd/cCkEicDMrjtrnMGQ1QFI9gWN1zGq8=
4+
github.com/labstack/echo/v4 v4.11.4/go.mod h1:noh7EvLwqDsmh/X/HWKPUl1AjzJrhyptRyEbQJfxen8=
5+
github.com/labstack/gommon v0.4.2 h1:F8qTUNXgG1+6WQmqoUWnz8WiEU60mXVVw0P4ht1WRA0=
6+
github.com/labstack/gommon v0.4.2/go.mod h1:QlUFxVM+SNXhDL/Z7YhocGIBYOiwB0mXm1+1bAPHPyU=
7+
github.com/mattn/go-colorable v0.1.13 h1:fFA4WZxdEF4tXPZVKMLwD8oUnCTTo08duU7wxecdEvA=
8+
github.com/mattn/go-colorable v0.1.13/go.mod h1:7S9/ev0klgBDR4GtXTXX8a3vIGJpMovkB8vQcUbaXHg=
9+
github.com/mattn/go-isatty v0.0.16/go.mod h1:kYGgaQfpe5nmfYZH+SKPsOc2e4SrIfOl2e/yFXSvRLM=
10+
github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
11+
github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
12+
github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
13+
github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
14+
github.com/stretchr/testify v1.8.4 h1:CcVxjf3Q8PM0mHUKJCdn+eZZtm5yQwehR5yeSVQQcUk=
15+
github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=
16+
github.com/valyala/bytebufferpool v1.0.0 h1:GqA5TC/0021Y/b9FG4Oi9Mr3q7XYx6KllzawFIhcdPw=
17+
github.com/valyala/bytebufferpool v1.0.0/go.mod h1:6bBcMArwyJ5K/AmCkWv1jt77kVWyCJ6HpOuEn7z0Csc=
18+
github.com/valyala/fasttemplate v1.2.2 h1:lxLXG0uE3Qnshl9QyaK6XJxMXlQZELvChBOCmQD0Loo=
19+
github.com/valyala/fasttemplate v1.2.2/go.mod h1:KHLXt3tVN2HBp8eijSv/kGJopbvo7S+qRAEEKiv+SiQ=
20+
golang.org/x/crypto v0.17.0 h1:r8bRNjWL3GshPW3gkd+RpvzWrZAwPS49OmTGZ/uhM4k=
21+
golang.org/x/crypto v0.17.0/go.mod h1:gCAAfMLgwOJRpTjQ2zCCt2OcSfYMTeZVSRtQlPC7Nq4=
22+
golang.org/x/crypto v0.22.0 h1:g1v0xeRhjcugydODzvb3mEM9SQ0HGp9s/nh3COQ/C30=
23+
golang.org/x/crypto v0.22.0/go.mod h1:vr6Su+7cTlO45qkww3VDJlzDn0ctJvRgYbC2NvXHt+M=
24+
golang.org/x/net v0.19.0 h1:zTwKpTd2XuCqf8huc7Fo2iSy+4RHPd10s4KzeTnVr1c=
25+
golang.org/x/net v0.19.0/go.mod h1:CfAk/cbD4CthTvqiEl8NpboMuiuOYsAr/7NOjZJtv1U=
26+
golang.org/x/net v0.21.0 h1:AQyQV4dYCvJ7vGmJyKki9+PBdyvhkSd8EIx/qb0AYv4=
27+
golang.org/x/net v0.21.0/go.mod h1:bIjVDfnllIU7BJ2DNgfnXvpSvtn8VRwhlsaeUTyUS44=
28+
golang.org/x/sys v0.0.0-20220811171246-fbc7d0a398ab/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
29+
golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
30+
golang.org/x/sys v0.15.0 h1:h48lPFYpsTvQJZF4EKyI4aLHaev3CxivZmv7yZig9pc=
31+
golang.org/x/sys v0.15.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
32+
golang.org/x/sys v0.19.0 h1:q5f1RH2jigJ1MoAWp2KTp3gm5zAGFUTarQZ5U386+4o=
33+
golang.org/x/sys v0.19.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
34+
golang.org/x/text v0.14.0 h1:ScX5w1eTa3QqT8oi6+ziP7dTV1S2+ALU0bI+0zXKWiQ=
35+
golang.org/x/text v0.14.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU=
36+
gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
37+
gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

‎_examples/echo/main.go

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
package main
2+
3+
import (
4+
"github.com/labstack/echo/v4"
5+
"github.com/rookie-luochao/go-openapi-ui"
6+
echoredoc "github.com/rookie-luochao/go-openapi-ui/echo"
7+
)
8+
9+
func main() {
10+
doc := doc.Doc{
11+
Title: "Example API",
12+
Description: "Example API Description",
13+
SpecFile: "./openapi.json",
14+
SpecPath: "/openapi.json",
15+
DocsPath: "/docs",
16+
}
17+
18+
r := echo.New()
19+
r.Use(echoredoc.New(doc))
20+
21+
println("Documentation served at http://127.0.0.1:8000/docs")
22+
panic(r.Start(":8000"))
23+
}

‎_examples/echo/openapi.json

+1
Large diffs are not rendered by default.

‎_examples/fiber/go.mod

+27
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
module github.com/rookie-luochao/go-openapi-ui/_examples/fiber
2+
3+
go 1.21.6
4+
5+
replace github.com/rookie-luochao/go-openapi-ui => ../../
6+
replace github.com/rookie-luochao/go-openapi-ui/fiber => ../../fiber
7+
8+
require (
9+
github.com/gofiber/fiber/v2 v2.52.0
10+
github.com/rookie-luochao/go-openapi-ui v0.0.0
11+
github.com/rookie-luochao/go-openapi-ui/fiber v0.0.0
12+
)
13+
14+
require (
15+
github.com/andybalholm/brotli v1.0.5 // indirect
16+
github.com/gofiber/adaptor/v2 v2.2.1 // indirect
17+
github.com/google/uuid v1.5.0 // indirect
18+
github.com/klauspost/compress v1.17.0 // indirect
19+
github.com/mattn/go-colorable v0.1.13 // indirect
20+
github.com/mattn/go-isatty v0.0.20 // indirect
21+
github.com/mattn/go-runewidth v0.0.15 // indirect
22+
github.com/rivo/uniseg v0.2.0 // indirect
23+
github.com/valyala/bytebufferpool v1.0.0 // indirect
24+
github.com/valyala/fasthttp v1.51.0 // indirect
25+
github.com/valyala/tcplisten v1.0.0 // indirect
26+
golang.org/x/sys v0.15.0 // indirect
27+
)

‎_examples/fiber/go.sum

+37
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
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/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
4+
github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
5+
github.com/gofiber/adaptor/v2 v2.2.1 h1:givE7iViQWlsTR4Jh7tB4iXzrlKBgiraB/yTdHs9Lv4=
6+
github.com/gofiber/adaptor/v2 v2.2.1/go.mod h1:AhR16dEqs25W2FY/l8gSj1b51Azg5dtPDmm+pruNOrc=
7+
github.com/gofiber/fiber/v2 v2.52.0 h1:S+qXi7y+/Pgvqq4DrSmREGiFwtB7Bu6+QFLuIHYw/UE=
8+
github.com/gofiber/fiber/v2 v2.52.0/go.mod h1:KEOE+cXMhXG0zHc9d8+E38hoX+ZN7bhOtgeF2oT6jrQ=
9+
github.com/google/uuid v1.5.0 h1:1p67kYwdtXjb0gL0BPiP1Av9wiZPo5A8z2cWkTZ+eyU=
10+
github.com/google/uuid v1.5.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
11+
github.com/klauspost/compress v1.17.0 h1:Rnbp4K9EjcDuVuHtd0dgA4qNuv9yKDYKK1ulpJwgrqM=
12+
github.com/klauspost/compress v1.17.0/go.mod h1:ntbaceVETuRiXiv4DpjP66DpAtAGkEQskQzEyD//IeE=
13+
github.com/mattn/go-colorable v0.1.13 h1:fFA4WZxdEF4tXPZVKMLwD8oUnCTTo08duU7wxecdEvA=
14+
github.com/mattn/go-colorable v0.1.13/go.mod h1:7S9/ev0klgBDR4GtXTXX8a3vIGJpMovkB8vQcUbaXHg=
15+
github.com/mattn/go-isatty v0.0.16/go.mod h1:kYGgaQfpe5nmfYZH+SKPsOc2e4SrIfOl2e/yFXSvRLM=
16+
github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
17+
github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
18+
github.com/mattn/go-runewidth v0.0.15 h1:UNAjwbU9l54TA3KzvqLGxwWjHmMgBUVhBiTjelZgg3U=
19+
github.com/mattn/go-runewidth v0.0.15/go.mod h1:Jdepj2loyihRzMpdS35Xk/zdY8IAYHsh153qUoGf23w=
20+
github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
21+
github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
22+
github.com/rivo/uniseg v0.2.0 h1:S1pD9weZBuJdFmowNwbpi7BJ8TNftyUImj/0WQi72jY=
23+
github.com/rivo/uniseg v0.2.0/go.mod h1:J6wj4VEh+S6ZtnVlnTBMWIodfgj8LQOQFoIToxlJtxc=
24+
github.com/stretchr/testify v1.8.4 h1:CcVxjf3Q8PM0mHUKJCdn+eZZtm5yQwehR5yeSVQQcUk=
25+
github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=
26+
github.com/valyala/bytebufferpool v1.0.0 h1:GqA5TC/0021Y/b9FG4Oi9Mr3q7XYx6KllzawFIhcdPw=
27+
github.com/valyala/bytebufferpool v1.0.0/go.mod h1:6bBcMArwyJ5K/AmCkWv1jt77kVWyCJ6HpOuEn7z0Csc=
28+
github.com/valyala/fasthttp v1.51.0 h1:8b30A5JlZ6C7AS81RsWjYMQmrZG6feChmgAolCl1SqA=
29+
github.com/valyala/fasthttp v1.51.0/go.mod h1:oI2XroL+lI7vdXyYoQk03bXBThfFl2cVdIA3Xl7cH8g=
30+
github.com/valyala/tcplisten v1.0.0 h1:rBHj/Xf+E1tRGZyWIWwJDiRY0zc1Js+CV5DqwacVSA8=
31+
github.com/valyala/tcplisten v1.0.0/go.mod h1:T0xQ8SeCZGxckz9qRXTfG43PvQ/mcWh7FwZEA7Ioqkc=
32+
golang.org/x/sys v0.0.0-20220811171246-fbc7d0a398ab/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
33+
golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
34+
golang.org/x/sys v0.15.0 h1:h48lPFYpsTvQJZF4EKyI4aLHaev3CxivZmv7yZig9pc=
35+
golang.org/x/sys v0.15.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
36+
gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
37+
gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

‎_examples/fiber/main.go

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
package main
2+
3+
import (
4+
"github.com/gofiber/fiber/v2"
5+
"github.com/rookie-luochao/go-openapi-ui"
6+
fiberredoc "github.com/rookie-luochao/go-openapi-ui/fiber"
7+
)
8+
9+
func main() {
10+
doc := doc.Doc{
11+
Title: "Example API",
12+
Description: "Example API Description",
13+
SpecFile: "./openapi.json",
14+
SpecPath: "/openapi.json",
15+
DocsPath: "/docs",
16+
}
17+
18+
r := fiber.New()
19+
r.Use(fiberredoc.New(doc))
20+
21+
println("Documentation served at http://127.0.0.1:8000/docs")
22+
panic(r.Listen(":8000"))
23+
}

‎_examples/fiber/openapi.json

+1
Large diffs are not rendered by default.

‎_examples/gen/Makefile

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
build: generate
2+
go build
3+
4+
generate:
5+
go generate

‎_examples/gen/docs/docs.go

+37
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)