Anton Troyanov
6433b1c297
* feat(ui): configure default expansion depth for models This commit adds possibility to configure defaultModelsExpandDepth, which controls how models (at the bottom of the API doc) are displayed. Default value is 1, but it can be set to -1 completely hide the models. https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/configuration.md#display * doc: update README.md Added Configuration section describing available configuration options.
152 lines
4.5 KiB
Markdown
152 lines
4.5 KiB
Markdown
# gin-swagger
|
||
|
||
gin middleware to automatically generate RESTFUL API documentation with Swagger 2.0.
|
||
|
||
[](https://github.com/features/actions)
|
||
[](https://codecov.io/gh/swaggo/gin-swagger)
|
||
[](https://goreportcard.com/report/github.com/swaggo/gin-swagger)
|
||
[](https://godoc.org/github.com/swaggo/gin-swagger)
|
||
|
||
|
||
## Usage
|
||
|
||
### Start using it
|
||
1. Add comments to your API source code, [See Declarative Comments Format](https://swaggo.github.io/swaggo.io/declarative_comments_format/).
|
||
2. Download [Swag](https://github.com/swaggo/swag) for Go by using:
|
||
```sh
|
||
go get -u github.com/swaggo/swag/cmd/swag
|
||
```
|
||
|
||
3. Run the [Swag](https://github.com/swaggo/swag) at your Go project root path(for instance `~/root/go-peoject-name`),
|
||
[Swag](https://github.com/swaggo/swag) will parse comments and generate required files(`docs` folder and `docs/doc.go`)
|
||
at `~/root/go-peoject-name/docs`.
|
||
```sh
|
||
swag init
|
||
```
|
||
4. Download [gin-swagger](https://github.com/swaggo/gin-swagger) by using:
|
||
```sh
|
||
go get -u github.com/swaggo/gin-swagger
|
||
go get -u github.com/swaggo/files
|
||
```
|
||
Import following in your code:
|
||
|
||
```go
|
||
import "github.com/swaggo/gin-swagger" // gin-swagger middleware
|
||
import "github.com/swaggo/files" // swagger embed files
|
||
|
||
```
|
||
|
||
### Canonical example:
|
||
Now assume you have implemented a simple api as following:
|
||
```go
|
||
// A get function which returns a hello world string by json
|
||
func Helloworld(g *gin.Context) {
|
||
g.JSON(http.StatusOK,"helloworld")
|
||
}
|
||
|
||
```
|
||
So how to use gin-swagger on api above? Just follow the following guide.
|
||
|
||
1. Add Comments for apis and main function with gin-swagger rules like following:
|
||
```go
|
||
// @BasePath /api/v1
|
||
|
||
// PingExample godoc
|
||
// @Summary ping example
|
||
// @Schemes
|
||
// @Description do ping
|
||
// @Tags example
|
||
// @Accept json
|
||
// @Produce json
|
||
// @Success 200 {string} Helloworld
|
||
// @Router /example/helloworld [get]
|
||
func Helloworld(g *gin.Context) {
|
||
g.JSON(http.StatusOK,"helloworld")
|
||
}
|
||
```
|
||
|
||
2. Use `swag init` command to generate a docs, docs generated will be stored at
|
||
3. import the docs like this:
|
||
I assume your project named `github.com/go-project-name/docs`.
|
||
```go
|
||
import (
|
||
docs "github.com/go-project-name/docs"
|
||
)
|
||
```
|
||
4. build your application and after that, go to http://localhost:8080/swagger/index.html ,you to see your Swagger UI.
|
||
|
||
5. The full code and folder relatives here:
|
||
```go
|
||
package main
|
||
|
||
import (
|
||
"github.com/gin-gonic/gin"
|
||
docs "github.com/go-project-name/docs"
|
||
swaggerfiles "github.com/swaggo/files"
|
||
ginSwagger "github.com/swaggo/gin-swagger"
|
||
"net/http"
|
||
)
|
||
// @BasePath /api/v1
|
||
|
||
// PingExample godoc
|
||
// @Summary ping example
|
||
// @Schemes
|
||
// @Description do ping
|
||
// @Tags example
|
||
// @Accept json
|
||
// @Produce json
|
||
// @Success 200 {string} Helloworld
|
||
// @Router /example/helloworld [get]
|
||
func Helloworld(g *gin.Context) {
|
||
g.JSON(http.StatusOK,"helloworld")
|
||
}
|
||
|
||
func main() {
|
||
r := gin.Default()
|
||
docs.SwaggerInfo.BasePath = "/api/v1"
|
||
v1 := r.Group("/api/v1")
|
||
{
|
||
eg := v1.Group("/example")
|
||
{
|
||
eg.GET("/helloworld",Helloworld)
|
||
}
|
||
}
|
||
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerfiles.Handler))
|
||
r.Run(":8080")
|
||
|
||
}
|
||
```
|
||
Demo project tree, `swag init` is run at relative `.`
|
||
```
|
||
.
|
||
├── docs
|
||
│ ├── docs.go
|
||
│ ├── swagger.json
|
||
│ └── swagger.yaml
|
||
├── go.mod
|
||
├── go.sum
|
||
└── main.go
|
||
```
|
||
|
||
## Configuration
|
||
|
||
You can configure Swagger using different configuration options
|
||
|
||
```go
|
||
func main() {
|
||
r := gin.New()
|
||
|
||
ginSwagger.WrapHandler(swaggerFiles.Handler,
|
||
ginSwagger.URL("http://localhost:8080/swagger/doc.json"),
|
||
ginSwagger.DefaultModelsExpandDepth(-1)))
|
||
|
||
r.Run()
|
||
}
|
||
```
|
||
|
||
| Option | Type | Default | Description |
|
||
|--------------------------|--------|------------|---------------------------------------------------------------------------|
|
||
| URL | string | "doc.json" | URL pointing to API definition |
|
||
| DeepLinking | bool | true | Swagger deeplinking configuration |
|
||
| DefaultModelsExpandDepth | int | 1 | Default expansion depth for models (set to -1 completely hide the models) |
|