iris-contrib / swagger Goto Github PK

View Code? Open in Web Editor NEW

116.0 4.0 32.0 11.29 MB

Iris middleware to automatically generate RESTful API documentation with Swagger 2.0

License: MIT License

Go 100.00%

iris-swagger iris golang swagger swaggo middleware iris-golang

swagger's Introduction

Swagger for the Iris web framework

Iris middleware to automatically generate RESTful API documentation with Swagger 2.0 as requested at #1231.

Usage

Start using it

Add comments to your API source code, See Declarative Comments Format.
Download Swag for Go by using:

$ 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 [email protected]: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

Run the Swag in your Go project root folder which contains main.go file, Swag will parse comments and generate required files(docs folder and docs/doc.go).

$ swag init

Download swagger for Iris by using:

$ go get github.com/iris-contrib/swagger/v12@master

And import following in your code:

import "github.com/iris-contrib/swagger" // swagger middleware for Iris 
import "github.com/iris-contrib/swagger/swaggerFiles" // swagger embed files

Example Code:

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 [email protected]

// @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")
}

Run it, and navigate through http://localhost:8080/swagger/index.html, you should see the Swagger 2.0 API documentation page.
If you want to disable swagger when some environment variable is set, use DisablingHandler instead of Handler.

swagger.DisablingHandler(swaggerFiles.Handler, "THE_OS_VARIABLE_NAME_HERE", configurators ...Configurator)

If you want to change swagger-ui theme, you can add swagger.SetTheme(swagger.Monokai) when init swaggerUI

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),
)

swagger's People

Contributors

Stargazers

Watchers

swagger's Issues

Can anyone please tell me what am I doing wrong here ?

The rest of the main.go file

package main

import (
	"github.com/kataras/iris/v12"
	"github.com/kataras/iris/v12/middleware/recover"

	"github.com/iris-contrib/swagger/v12"              // swagger middleware for Iris
	"github.com/iris-contrib/swagger/v12/swaggerFiles" // swagger embed files

	"go.api.backend/api/endpoints"
	_ "go.api.backend/docs"
)

// @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 [email protected]

// @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()

	// Built-in
	app.UseRouter(recover.New()) //Recovery middleware recovers from any panics and writes a 500 if there was one.

	endpoints.BookRegister(app)

	//region ======== SWAGGER REGISTRATIONS =================================================

swagger parma type

Describe the issue you are facing or ask for help

@kataras Is the document wrong?

Why can't users read it, but users can

// @success 200 {object} model.User

v11 can not work

go get github.com/iris-contrib/swagger: no matching versions for query "upgrade"

docs/docs.go:11:2: cannot find package

Hi，
$ go run main.go
docs/docs.go:11:2: cannot find package
$

DeepLinking is not work

I configured DeepLinking is true , but it is not work.
When I use the url with id to access the webpage, the corresponding page cannot be opened, and the homepage is always displayed

ps: the url like this( http://localhost/index.html#/user/account_getuser )

How to configure swagger comments with iris using mvc

....
	mvc.Configure(app.Party("/api/v1"), func(m *mvc.Application) {
		m.Party("/test").Handle(new(v1.Test))
		m.Party("/xiaomai").Handle(new(v1.XiaoMai))
	})
.....

type XiaoMai  struct {
	Ctx iris.Context
}

// @Summary
// @Produce json
// @Param text string true "text"
// @Success 200 {object} restful.JsonResult
// @Failure 500 {object} restful.JsonResult
// @Router /api/v1/tiktok/parse/video
func (t *XiaoMai) PostParseVideo() *restful.JsonResult {
......
......
}

the questions about api operation .

When i set api operations->params type-> array . The Ui notice me
Could not render this component, see the console. ? So, it's means params type is not support array?.

Request Method is OPTIONS when Post Json

When I use the POST method to accept the JSON parameter, click the Try it out button, and swagger sends an OPTIONS type request.

here is my code：

// @Accept  json
// @Param req body bean.Dog true "InstanceCreateReq"
// @Success 200 {string} string	"ok"
// @Router /demo/dog [post]

the request by swagger try is：

Request URL: http://127.0.0.1:8888/demo/dog
Request Method: OPTIONS
Status Code: 404 Not Found
Remote Address: 127.0.0.1:8888
Referrer Policy: no-referrer-when-downgrade

The module value in the go.mod is wrong

In the release: v12.2.0-alpha2 , the value in the go.mod is module github.com/iris-contrib/swagger

should it be module github.com/iris-contrib/swagger/v12 ?

I can not download it in my project with go mod with error:

go: github.com/iris-contrib/swagger/[email protected]: go.mod has non-.../v12 module path "github.com/iris-contrib/swagger" (and .../v12/go.mod does not exist) at revision v12.2.0-alpha2

swagger doesn't work when I use app.Party

v1 := app.Party("/api/v1")
v1.Post("/user/login", ...

swagger path is /user/login

Endpoint grouping/collection

How can I group the endpoints by Party ? Which declaration/annotation comment should I use ? I'm having this:

I need the endpoints grouped by something like "Books", "Catalogs" and so on,... not one unique unnamed "default" group. How can I achieve that?

PS: My problem is similar to this link but with Iris

@success Format support

Do you support the following formats?
@success 200 {object} jsonresult.JSONResult{data=proto.Order} "desc"

How to use swagger with different instance names

Describe the bug
I'm generating swagger documentation by running swag init --instanceName auth

To Reproduce
Steps to reproduce the behavior:

Create a simple go project, using iris
Create a swagger folder in your project root
Generate multiple swagger docs using different instancenames. For example:

cd <Project-Root>/swagger
swag init -dir ../cmd/myproject --instanceName main
swag init -dir ../pkg/auth --instanceName auth
swag init -dir ../pkg/anotherPackage --instanceName anotherPackage

In your main.go, one should be able to register multiple instance names against differnet url paths. E.g. ginSwagger does it this way:

router.GET("/swagger/main/*any", ginSwagger.WrapHandler(swaggerFiles.Handler, ginSwagger.InstanceName("main")))
router.GET("/swagger/auth/*any", ginSwagger.WrapHandler(swaggerFiles.Handler, ginSwagger.InstanceName("auth")))
router.GET("/swagger/anotherPackage/*any", ginSwagger.WrapHandler(swaggerFiles.Handler, ginSwagger.InstanceName("anotherPackage")))

For more details, please refer to this:
https://myschools.me/suguo/gin-swagger/src/commit/88c9ed2643de9f3b9fd2ac9ad03d9e63bd7721d3/example/multiple/main.go

Expected behavior
I should be able to define and use different instance names as I need to consolidate and generate swagger documentation for all of my packages at one place.

Screenshots
Not applicable

Desktop (please complete the following information):

OS: MAC

iris.Version

github.com/iris-contrib/swagger/v12 v12.2.0-alpha
github.com/kataras/iris/v12 v12.2.0-beta7.0.20230219194850-dccd57263617
github.com/swaggo/swag v1.8.10

Will swagger work like yaag?

Will this swagger automatic generate API docs after calling API, without pre-write annotation on API?

It does not read code annotation between two project

Hi，it can not read code annotation between to project. How can i resolve it? Thank you.

[FEATURE REQUEST] Custom oauth2RedirectUrl

Is your feature request related to a problem? Please describe.
My project is running locally with port 44000 but Swagger always redirects to localhost:3200. I want to change oauth2RedirectUrl so it can redirect properly.

Describe the solution you'd like

swaggerUI := swagger.WrapHandler(swaggerFiles.Handler, swagger.Config{
  Oauth2RedirectUrl: "http://localhost:44000",
})

Cannot get latest version (v12.2.0)

Describe the bug
The latest version (v12.2.0 at the moment) is effectivly un-gettable.