apidoc

package module
v0.6.6 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 1, 2026 License: BSD-3-Clause Imports: 16 Imported by: 2

Documentation

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Generator

type Generator struct {
	// contains filtered or unexported fields
}

func New

func New(title, ver, desc string) *Generator

func (*Generator) ReDocUI

func (sg *Generator) ReDocUI(svc ...desc.ServiceDesc) (fs.FS, error)

func (*Generator) ScalarUI added in v0.2.19

func (sg *Generator) ScalarUI(svc ...desc.ServiceDesc) (fs.FS, error)

func (*Generator) SwaggerUI

func (sg *Generator) SwaggerUI(svc ...desc.ServiceDesc) (fs.FS, error)

func (*Generator) WithTag

func (sg *Generator) WithTag(tagName string) *Generator

func (*Generator) WritePostmanTo

func (sg *Generator) WritePostmanTo(w io.Writer, descs ...desc.ServiceDesc) error

func (*Generator) WritePostmanToFile

func (sg *Generator) WritePostmanToFile(filename string, services ...desc.ServiceDesc) error
Example
package main

import (
	"fmt"
	"time"

	"github.com/clubpay/ronykit/kit"
	"github.com/clubpay/ronykit/kit/desc"
	"github.com/clubpay/ronykit/std/gateways/fasthttp"
	"github.com/clubpay/ronykit/x/apidoc"
)

type embedded struct {
	Embedded string `json:"embedded"`
	Others   string `json:"others"`
}

type iErr interface {
	ErrorDetails()
}

type sampleReq struct {
	embedded
	TT     [][]string        `json:"tt"`
	X      string            `json:"x,int" swag:"enum:1,2,3"`
	Y      string            `json:"y,omitempty"`
	Z      int64             `json:"z" swag:"deprecated;optional"`
	W      []string          `json:"w"`
	MS     map[string]subRes `json:"ms"`
	MSS    map[string]string `json:"mss"`
	MIS    map[int]string    `json:"mis"`
	MII    map[int]int       `json:"mii"`
	MIA    map[string]any    `json:"mia"`
	CT     time.Time         `json:"ct"`
	CTP    *time.Time        `json:"ctp"`
	ErrMsg iErr              `json:"err"`
}

type subRes struct {
	Some    string `json:"some"`
	Another []byte `json:"another"`
}

type sampleRes struct {
	Out1  int       `json:"out1"`
	Out2  string    `json:"out2"`
	Sub   subRes    `json:"sub"`
	Subs  []subRes  `json:"subs,omitempty"`
	XSub  *subRes   `json:"xSub"`
	Subs2 []*subRes `json:"subs2,omitempty"`
}

type sampleError struct {
	Code int    `json:"code" swag:"enum:504,503"`
	Item string `json:"item"`
}

func (e sampleError) GetCode() int {
	return e.Code
}

func (e sampleError) GetItem() string {
	return e.Item
}

func (e sampleError) Error() string {
	return fmt.Sprintf("%d: %s", e.Code, e.Item)
}

type anotherRes struct {
	subRes
	Out1 int    `json:"out1" swag:"deprecated"`
	Out2 string `json:"out2" swag:"enum:OUT1,OUT2"`
}

type testService struct{}

func (t testService) Desc() *desc.Service {
	return (&desc.Service{
		Name: "testService",
	}).
		AddContract(
			desc.NewContract().
				SetName("sumGET").
				AddRoute(desc.Route("", fasthttp.GET("/some/:x/:y"))).
				SetInput(&sampleReq{}).
				SetOutput(&sampleRes{}).
				AddError(&sampleError{404, "ITEM1"}).
				AddError(&sampleError{504, "SERVER"}).
				SetHandler(nil),
		).
		AddContract(
			desc.NewContract().
				SetName("sumPOST").
				AddRoute(desc.Route("", fasthttp.POST("/some/:x/:y"))).
				SetInput(&sampleReq{}).
				SetOutput(&anotherRes{}).
				SetHandler(nil),
		).
		AddContract(
			desc.NewContract().
				SetName("sumPOST2").
				AddRoute(desc.Route("", fasthttp.POST("/some/something-else"))).
				SetInput(kit.RawMessage{}).
				SetOutput(kit.RawMessage{}).
				SetHandler(nil),
		).
		AddContract(
			desc.NewContract().
				SetName("upload").
				AddRoute(desc.Route("", fasthttp.POST("/upload"))).
				SetInput(kit.MultipartFormMessage{},
					desc.WithField("file", desc.FieldMeta{
						FormData: &desc.FormDataValue{Name: "file", Type: "file"},
					}),
				).
				SetOutput(kit.RawMessage{}).
				SetHandler(nil),
		)
}

func main() {
	err := apidoc.New("TestTitle", "v0.0.1", "").
		WithTag("json").
		WritePostmanToFile("_postman.json", testService{})
	fmt.Println(err)
}
Output:
<nil>

func (*Generator) WriteSwagTo

func (sg *Generator) WriteSwagTo(w io.Writer, descs ...desc.ServiceDesc) error

func (*Generator) WriteSwagToFile

func (sg *Generator) WriteSwagToFile(filename string, services ...desc.ServiceDesc) error
Example
package main

import (
	"fmt"
	"time"

	"github.com/clubpay/ronykit/kit"
	"github.com/clubpay/ronykit/kit/desc"
	"github.com/clubpay/ronykit/std/gateways/fasthttp"
	"github.com/clubpay/ronykit/x/apidoc"
)

type embedded struct {
	Embedded string `json:"embedded"`
	Others   string `json:"others"`
}

type iErr interface {
	ErrorDetails()
}

type sampleReq struct {
	embedded
	TT     [][]string        `json:"tt"`
	X      string            `json:"x,int" swag:"enum:1,2,3"`
	Y      string            `json:"y,omitempty"`
	Z      int64             `json:"z" swag:"deprecated;optional"`
	W      []string          `json:"w"`
	MS     map[string]subRes `json:"ms"`
	MSS    map[string]string `json:"mss"`
	MIS    map[int]string    `json:"mis"`
	MII    map[int]int       `json:"mii"`
	MIA    map[string]any    `json:"mia"`
	CT     time.Time         `json:"ct"`
	CTP    *time.Time        `json:"ctp"`
	ErrMsg iErr              `json:"err"`
}

type subRes struct {
	Some    string `json:"some"`
	Another []byte `json:"another"`
}

type sampleRes struct {
	Out1  int       `json:"out1"`
	Out2  string    `json:"out2"`
	Sub   subRes    `json:"sub"`
	Subs  []subRes  `json:"subs,omitempty"`
	XSub  *subRes   `json:"xSub"`
	Subs2 []*subRes `json:"subs2,omitempty"`
}

type sampleError struct {
	Code int    `json:"code" swag:"enum:504,503"`
	Item string `json:"item"`
}

func (e sampleError) GetCode() int {
	return e.Code
}

func (e sampleError) GetItem() string {
	return e.Item
}

func (e sampleError) Error() string {
	return fmt.Sprintf("%d: %s", e.Code, e.Item)
}

type anotherRes struct {
	subRes
	Out1 int    `json:"out1" swag:"deprecated"`
	Out2 string `json:"out2" swag:"enum:OUT1,OUT2"`
}

type testService struct{}

func (t testService) Desc() *desc.Service {
	return (&desc.Service{
		Name: "testService",
	}).
		AddContract(
			desc.NewContract().
				SetName("sumGET").
				AddRoute(desc.Route("", fasthttp.GET("/some/:x/:y"))).
				SetInput(&sampleReq{}).
				SetOutput(&sampleRes{}).
				AddError(&sampleError{404, "ITEM1"}).
				AddError(&sampleError{504, "SERVER"}).
				SetHandler(nil),
		).
		AddContract(
			desc.NewContract().
				SetName("sumPOST").
				AddRoute(desc.Route("", fasthttp.POST("/some/:x/:y"))).
				SetInput(&sampleReq{}).
				SetOutput(&anotherRes{}).
				SetHandler(nil),
		).
		AddContract(
			desc.NewContract().
				SetName("sumPOST2").
				AddRoute(desc.Route("", fasthttp.POST("/some/something-else"))).
				SetInput(kit.RawMessage{}).
				SetOutput(kit.RawMessage{}).
				SetHandler(nil),
		).
		AddContract(
			desc.NewContract().
				SetName("upload").
				AddRoute(desc.Route("", fasthttp.POST("/upload"))).
				SetInput(kit.MultipartFormMessage{},
					desc.WithField("file", desc.FieldMeta{
						FormData: &desc.FormDataValue{Name: "file", Type: "file"},
					}),
				).
				SetOutput(kit.RawMessage{}).
				SetHandler(nil),
		)
}

func main() {
	err := apidoc.New("TestTitle", "v0.0.1", "").
		WithTag("json").
		WriteSwagToFile("_swagger.json", testService{})
	fmt.Println(err)
}
Output:
<nil>

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址