Skip to content

Commit

Permalink
add zh readme; reduce some dependencies
Browse files Browse the repository at this point in the history
  • Loading branch information
@zc2638
zc2638 committed Jun 7, 2022
1 parent 7e2e298 commit 1039a54
Show file tree
Hide file tree
Showing 4 changed files with 551 additions and 125 deletions.
230 changes: 116 additions & 114 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,9 @@
[![GoDoc](https://godoc.org/github.com/zc2638/swag?status.svg)](https://godoc.org/github.com/zc2638/swag)
[![Go Report Card](https://goreportcard.com/badge/github.com/zc2638/swag)](https://goreportcard.com/report/github.com/zc2638/swag)

```swag``` is a lightweight library to generate swagger json for Go projects.
English | [简体中文](./README_zh.md)

```swag``` is a lightweight library to generate swagger json for Golang projects.

```swag``` is heavily geared towards generating REST/JSON apis.

Expand Down Expand Up @@ -39,8 +41,8 @@ However, it'll probably be useful if you include definitions of what ```GET /pet

```go
allPets := endpoint.New("get", "/pet", "Return all the pets",
endpoint.Response(http.StatusOk, Pet{}, "Successful operation"),
endpoint.Response(http.StatusInternalServerError, Error{}, "Oops ... something went wrong"),
endpoint.Response(http.StatusOk, Pet{}, "Successful operation"),
endpoint.Response(http.StatusInternalServerError, Error{}, "Oops ... something went wrong"),
)
```

Expand All @@ -53,35 +55,35 @@ See the complete example below for how ```Walk``` can be used to bind endpoints

```go
api := swag.New(
option.Title("Swagger Petstore"),
option.Endpoints(post, get),
option.Title("Swagger Petstore"),
option.Endpoints(post, get),
)

// iterate over each endpoint, if we've defined a handler, we can use it to bind to the router. We're using ```gin``
// in this example, but any web framework will do.
router := gin.New()
api.Walk(func (path string, e *swag.Endpoint) {
h := e.Handler.(func (c *gin.Context))
path = swag.ColonPath(path)
router.Handle(e.Method, path, h)
h := e.Handler.(func (c *gin.Context))
path = swag.ColonPath(path)
router.Handle(e.Method, path, h)
})
```

## Default Swagger UI Server

```go
func main() {
handle := swag.UIHandler("/swagger/ui", "", false)
patterns := swag.UIPatterns("/swagger/ui")
for _, pattern := range patterns {
http.DefaultServeMux.Handle(pattern, handle)
}
handle := swag.UIHandler("/swagger/ui", "", false)
patterns := swag.UIPatterns("/swagger/ui")
for _, pattern := range patterns {
http.DefaultServeMux.Handle(pattern, handle)
}

log.Fatal(http.ListenAndServe(":8080", nil))
log.Fatal(http.ListenAndServe(":8080", nil))
}
```
so you can visit for config: `http://localhost:8080/swagger/json`
so you can visit for ui: `http://localhost:8080/swagger/ui`

so you can visit for UI: `http://localhost:8080/swagger/ui`

## Examples

Expand Down Expand Up @@ -169,18 +171,18 @@ func main() {

```go
func main() {
...
// Note: Built-in routes cannot automatically resolve path parameters.
for p, endpoints := range api.Paths {
http.DefaultServeMux.Handle(path.Join(api.BasePath, p), endpoints)
}
http.DefaultServeMux.Handle("/swagger/json", api.Handler())
patterns := swag.UIPatterns("/swagger/ui")
for _, pattern := range patterns {
http.DefaultServeMux.Handle(pattern, swag.UIHandler("/swagger/ui", "/swagger/json", true))
}

log.Fatal(http.ListenAndServe(":8080", nil))
...
// Note: Built-in routes cannot automatically resolve path parameters.
for p, endpoints := range api.Paths {
http.DefaultServeMux.Handle(path.Join(api.BasePath, p), endpoints)
}
http.DefaultServeMux.Handle("/swagger/json", api.Handler())
patterns := swag.UIPatterns("/swagger/ui")
for _, pattern := range patterns {
http.DefaultServeMux.Handle(pattern, swag.UIHandler("/swagger/ui", "/swagger/json", true))
}

log.Fatal(http.ListenAndServe(":8080", nil))
}

```
Expand All @@ -189,120 +191,120 @@ func main() {

```go
func main() {
...

router := gin.New()
api.Walk(func (path string, e *swag.Endpoint) {
h := e.Handler.(http.Handler)
path = swag.ColonPath(path)

router.Handle(e.Method, path, gin.WrapH(h))
})
// Register Swagger JSON route
router.GET("/swagger/json", gin.WrapH(api.Handler()))
// Register Swagger UI route
// To take effect, the swagger json route must be registered
router.GET("/swagger/ui/*any", gin.WrapH(swag.UIHandler("/swagger/ui", "/swagger/json", true)))

log.Fatal(http.ListenAndServe(":8080", router))
...

router := gin.New()
api.Walk(func (path string, e *swag.Endpoint) {
h := e.Handler.(http.Handler)
path = swag.ColonPath(path)

router.Handle(e.Method, path, gin.WrapH(h))
})

// Register Swagger JSON route
router.GET("/swagger/json", gin.WrapH(api.Handler()))

// Register Swagger UI route
// To take effect, the swagger json route must be registered
router.GET("/swagger/ui/*any", gin.WrapH(swag.UIHandler("/swagger/ui", "/swagger/json", true)))

log.Fatal(http.ListenAndServe(":8080", router))
}
```

### chi

```go
func main() {
...
router := chi.NewRouter()
api.Walk(func (path string, e *swag.Endpoint) {
router.Method(e.Method, path, e.Handler.(http.Handler))
})
router.Handle("/swagger/json", api.Handler())
router.Mount("/swagger/ui", swag.UIHandler("/swagger/ui", "/swagger/json", true))

log.Fatal(http.ListenAndServe(":8080", router))
...

router := chi.NewRouter()
api.Walk(func (path string, e *swag.Endpoint) {
router.Method(e.Method, path, e.Handler.(http.Handler))
})
router.Handle("/swagger/json", api.Handler())
router.Mount("/swagger/ui", swag.UIHandler("/swagger/ui", "/swagger/json", true))

log.Fatal(http.ListenAndServe(":8080", router))
}
```

### mux

```go
func main() {
...
router := mux.NewRouter()
api.Walk(func (path string, e *swag.Endpoint) {
h := e.Handler.(http.HandlerFunc)
router.Path(path).Methods(e.Method).Handler(h)
})
router.Path("/swagger/json").Methods("GET").Handler(api.Handler())
router.PathPrefix("/swagger/ui").Handler(swag.UIHandler("/swagger/ui", "/swagger/json", true))

log.Fatal(http.ListenAndServe(":8080", router))
...

router := mux.NewRouter()
api.Walk(func (path string, e *swag.Endpoint) {
h := e.Handler.(http.HandlerFunc)
router.Path(path).Methods(e.Method).Handler(h)
})

router.Path("/swagger/json").Methods("GET").Handler(api.Handler())
router.PathPrefix("/swagger/ui").Handler(swag.UIHandler("/swagger/ui", "/swagger/json", true))

log.Fatal(http.ListenAndServe(":8080", router))
}
```

### echo

```go
func main() {
...
router := echo.New()
api.Walk(func (path string, e *swag.Endpoint) {
h := echo.WrapHandler(e.Handler.(http.Handler))
path = swag.ColonPath(path)
switch strings.ToLower(e.Method) {
case "get":
router.GET(path, h)
case "head":
router.HEAD(path, h)
case "options":
router.OPTIONS(path, h)
case "delete":
router.DELETE(path, h)
case "put":
router.PUT(path, h)
case "post":
router.POST(path, h)
case "trace":
router.TRACE(path, h)
case "patch":
router.PATCH(path, h)
case "connect":
router.CONNECT(path, h)
}
})
router.GET("/swagger/json", echo.WrapHandler(api.Handler()))
router.GET("/swagger/ui/*", echo.WrapHandler(swag.UIHandler("/swagger/ui", "/swagger/json", true)))

log.Fatal(http.ListenAndServe(":8080", router))
...

router := echo.New()
api.Walk(func (path string, e *swag.Endpoint) {
h := echo.WrapHandler(e.Handler.(http.Handler))
path = swag.ColonPath(path)

switch strings.ToLower(e.Method) {
case "get":
router.GET(path, h)
case "head":
router.HEAD(path, h)
case "options":
router.OPTIONS(path, h)
case "delete":
router.DELETE(path, h)
case "put":
router.PUT(path, h)
case "post":
router.POST(path, h)
case "trace":
router.TRACE(path, h)
case "patch":
router.PATCH(path, h)
case "connect":
router.CONNECT(path, h)
}
})

router.GET("/swagger/json", echo.WrapHandler(api.Handler()))
router.GET("/swagger/ui/*", echo.WrapHandler(swag.UIHandler("/swagger/ui", "/swagger/json", true)))

log.Fatal(http.ListenAndServe(":8080", router))
}
```

### httprouter

```go
func main() {
...
router := httprouter.New()
api.Walk(func (path string, e *swag.Endpoint) {
h := e.Handler.(http.Handler)
path = swag.ColonPath(path)
router.Handler(e.Method, path, h)
})
router.Handler(http.MethodGet, "/swagger/json", api.Handler())
router.Handler(http.MethodGet, "/swagger/ui/*any", swag.UIHandler("/swagger/ui", "/swagger/json", true))

log.Fatal(http.ListenAndServe(":8080", router))
...

router := httprouter.New()
api.Walk(func (path string, e *swag.Endpoint) {
h := e.Handler.(http.Handler)
path = swag.ColonPath(path)
router.Handler(e.Method, path, h)
})

router.Handler(http.MethodGet, "/swagger/json", api.Handler())
router.Handler(http.MethodGet, "/swagger/ui/*any", swag.UIHandler("/swagger/ui", "/swagger/json", true))

log.Fatal(http.ListenAndServe(":8080", router))
}
```

Expand Down
Loading

0 comments on commit 1039a54

Please sign in to comment.