https://github.com/iris-contrib/swagger
Iris middleware to automatically generate RESTful API documentation with Swagger 2.0
https://github.com/iris-contrib/swagger
golang iris iris-golang iris-swagger middleware swagger swaggo
Last synced: 3 months ago
JSON representation
Iris middleware to automatically generate RESTful API documentation with Swagger 2.0
- Host: GitHub
- URL: https://github.com/iris-contrib/swagger
- Owner: iris-contrib
- License: mit
- Created: 2019-04-14T02:14:24.000Z (almost 7 years ago)
- Default Branch: master
- Last Pushed: 2024-02-28T10:59:05.000Z (almost 2 years ago)
- Last Synced: 2024-11-13T15:53:46.352Z (about 1 year ago)
- Topics: golang, iris, iris-golang, iris-swagger, middleware, swagger, swaggo
- Language: Go
- Homepage:
- Size: 11 MB
- Stars: 115
- Watchers: 4
- Forks: 32
- Open Issues: 15
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# Swagger for the Iris web framework
[Iris](https://github.com/kataras/iris) middleware to automatically generate RESTful API documentation with Swagger 2.0 as requested at [#1231](https://github.com/kataras/iris/issues/1231).
[](https://github.com/iris-contrib/swagger/actions)
[](https://goreportcard.com/report/github.com/iris-contrib/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 install github.com/swaggo/swag/cmd/swag@latest
# if you find swag cli not work, you can try to install swag cli from source
git clone git@github.com:swaggo/swag.git
cd swag
# tag variable should match with github.com/swaggo/swag in go.mod
# here we use v1.8.10
git checkout -b ${tag} tags/${tag}
go install ./cmd/swag
```
3. Run the [Swag](https://github.com/swaggo/swag) in your Go project root folder which contains `main.go` file, [Swag](https://github.com/swaggo/swag) will parse comments and generate required files(`docs` folder and `docs/doc.go`).
```sh
$ swag init
```
4. Download [swagger for Iris](https://github.com/iris-contrib/swagger) by using:
```sh
$ go get github.com/iris-contrib/swagger/v12@master
```
And import following in your code:
```go
import "github.com/iris-contrib/swagger" // swagger middleware for Iris
import "github.com/iris-contrib/swagger/swaggerFiles" // swagger embed files
```
### Example Code:
```go
package main
import (
"github.com/kataras/iris/v12"
"github.com/iris-contrib/swagger"
"github.com/iris-contrib/swagger/swaggerFiles"
_ "github.com/your_username/your_project/docs"
// docs folder should be generated by Swag CLI (swag init),
// you have to import it.
)
// @title Swagger Example API
// @version 1.0
// @description This is a sample server Petstore server.
// @termsOfService http://swagger.io/terms/
// @contact.name API Support
// @contact.url http://www.swagger.io/support
// @contact.email support@swagger.io
// @license.name Apache 2.0
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html
// @host localhost:8080
// @BasePath /v2
func main() {
app := iris.New()
swaggerUI := swagger.Handler(swaggerFiles.Handler,
swagger.URL("/swagger/doc.json"),
swagger.DeepLinking(true),
swagger.Prefix("/swagger"),
)
// Register on http://localhost:8080/swagger
app.Get("/swagger", swaggerUI)
// And the wildcard one for index.html, *.js, *.css and e.t.c.
app.Get("/swagger/{any:path}", swaggerUI)
app.Listen(":8080")
}
```
5. Run it, and navigate through , you should see the Swagger 2.0 API documentation page.
6. If you want to disable swagger when some environment variable is set, use `DisablingHandler` instead of `Handler`.
```go
swagger.DisablingHandler(swaggerFiles.Handler, "THE_OS_VARIABLE_NAME_HERE", configurators ...Configurator)
```
7. If you want to change swagger-ui theme, you can add `swagger.SetTheme(swagger.Monokai)` when init `swaggerUI`
```go
swaggerUI := swagger.Handler(swaggerFiles.Handler,
swagger.URL("/swagger/doc.json"),
swagger.DeepLinking(true),
swagger.Prefix("/swagger"),
// ref: https://github.com/ostranme/swagger-ui-themes
// current we support 7 themes
// theme is a optional config, if you not set, it will use default theme
swagger.SetTheme(swagger.Monokai),
)
```