fiber_swagger

README

Fiber Swagger

目前还处于开发阶段

介绍

目前大多的 Golang web 框架的 OpenAPI 文档的生成是通过写注释的方式生成的，并且注释的的内容非常多，开发者其实大多数应该不喜欢写这样的注释。Filber_Swagger 通过在 Fiber web框架路由的地方做一些额外的绑定以及在定义接口的请求和响应的结构体中增加tag来实现自动生成 OpenAPI 相比于 通过大量注释的方式还是比较友好的，同时Filber_Swagger 在尽可能减少对Fiber 框架的的侵入。

使用说明

快速使用

func initSwagger() *fiber_swagger.Swagger {
	swag := fiber_swagger.NewSwagger(
		"fiber_swagger example",
		"fiber_swagger generate openapi document",
		"0.0.1",
		fiber_swagger.DocPath("./docs/openapi.yaml"),
	)
	return swag
}

初始化 OpenAPI 的基本信息，包含了 Title, Description,Version，以及生成 文档的路径。

定义请求或响应的数据结构：

type User struct {
	Id       int `json:"id" validate:"required" description:"用户的唯一标识"`
	UserBase `embed:""`
}

type UserBase struct {
	Name string `json:"name" validate:"required" description:"名字"`
	Age  int    `json:"age" validate:"required" description:"年龄"`
}

这里是为了做嵌套嵌套数据结构的示例，所以定义了 UserBase 数据结构和 User 数据结构，当 tag中存在 embed 时会展开数据结构到当前的数据结构

做绑定关联

func main() {
	app := fiber.New()
	swag := initSwagger()

	api := app.Group("api")

	user := api.Group("user")

	user.Post("/query_users", QueryUsers).Name("查询用户")
	swag.Bind("查询用户", nil, map[int]interface{}{
		http.StatusOK:                  &QueryUsersResult{},
		http.StatusInternalServerError: &FailedResponse{},
		http.StatusNoContent:           nil,
		http.StatusUnauthorized:        nil,
		http.StatusForbidden:           nil,
		http.StatusBadRequest:          &FailedResponse{},
	})

	swag.Generate(app)
}

在路由的的地方通过Name指定了每个路由的名称，同时通过这个名称并绑定了请求的数据结构和响应的数据结构，关于响应的数据库结构这里是定义了一个 map[int]interface{} 来保存，key 是 HTTP 的状态码，value 是对应状态码的数据结构，关于不同的状态码这里原本的期望是：

• http.StatusOK：请求成功，并返回 {"data": ""} 的数据结构
• http.StatusInternalServerError: 表示服务器内部错误, 返回 {"err":"",msg:""} 的数据结构
• http.StatusNoContent: 表示请求成功，但不返回数据结构
• http.StatusUnauthorized: 表示未认证，不返回数据结构
• http.StatusForbidden: 表示没有权限，不返回数据结构
• http.StatusBadRequest: 表示错误的请求，返回 {"err":"",msg:""} 的数据结构

目前 关于 不同的状态码的处理，是固定的，如 http.StatusNoContent 在生成 OpenAPI的处理是固定的：

func (s *Swagger) NoContentResponse() *openapi3.ResponseRef {
	return &openapi3.ResponseRef{
		Value: &openapi3.Response{
			Content:     nil,
			Description: &NOCONTENT,
		},
	}
}

func (s *Swagger) ForbiddenResponse() *openapi3.ResponseRef {
	return &openapi3.ResponseRef{
		Value: &openapi3.Response{
			Content:     nil,
			Description: &FORBIDDEN,
		},
	}
}

Documentation

Index

• Constants
• Variables
• type HttpRequestResponse
• type Option
  • func Contact(name, url, email string) Option
  • func Description(description string) Option
  • func DocPath(path string) Option
  • func License(name, url string) Option
  • func Title(title string) Option
  • func Version(version string) Option
• type Swagger
  • func NewSwagger(title, description, version string, options ...Option) *Swagger
  • func (s *Swagger) AddComponents(components ...interface{})
  • func (s *Swagger) Bind(name string, request interface{}, responses map[int]interface{})
  • func (s *Swagger) ForbiddenResponse() *openapi3.ResponseRef
  • func (s *Swagger) Generate(app *fiber.App)
  • func (s *Swagger) NoContentResponse() *openapi3.ResponseRef
  • func (s *Swagger) WriteToYaml() error

Constants

const (
	QUERY       = "query"
	JSON        = "json"
	FORM        = "form"
	URI         = "uri"
	HEADER      = "header"
	COOKIE      = "cookie"
	DEFAULT     = "default"
	VALIDATE    = "validate"
	DESCRIPTION = "description"
	EMBED       = "embed"
	EXAMPLE     = "example"
	EXCLUDE     = "exclude"
	TITLE       = "title"
	ENUM        = "enum"
)

Variables

var (
	SUCCESS   = "success"
	FAILED    = "failed"
	NOTFOUND  = "not found"
	FORBIDDEN = "forbidden"
	NOCONTENT = "no content"
)

Types

type HttpRequestResponse

type HttpRequestResponse struct {
	URLName   string
	Request   interface{}
	Responses map[int]interface{}
}

type Option

type Option func(swagger *Swagger)

func Contact

func Contact(name, url, email string) Option

func Description

func Description(description string) Option

func DocPath

func DocPath(path string) Option

func License

func License(name, url string) Option

func Title

func Title(title string) Option

func Version

func Version(version string) Option

type Swagger

type Swagger struct {
	Title             string
	Description       string
	Version           string
	License           *openapi3.License
	Contact           *openapi3.Contact
	Components        []interface{}
	OpenAPI           *openapi3.T
	Schemas           map[string]*openapi3.SchemaRef
	Paths             map[string]map[string]*router.Router
	PathResponseTypes map[string]map[int]interface{}
	OpenAPIYamlFile   string
	// contains filtered or unexported fields
}

func NewSwagger

func NewSwagger(title, description, version string, options ...Option) *Swagger

func (*Swagger) AddComponents

func (s *Swagger) AddComponents(components ...interface{})

func (*Swagger) Bind

func (s *Swagger) Bind(name string, request interface{}, responses map[int]interface{})

func (*Swagger) ForbiddenResponse

func (s *Swagger) ForbiddenResponse() *openapi3.ResponseRef

func (*Swagger) Generate

func (s *Swagger) Generate(app *fiber.App)

func (*Swagger) NoContentResponse

func (s *Swagger) NoContentResponse() *openapi3.ResponseRef

func (*Swagger) WriteToYaml

func (s *Swagger) WriteToYaml() error