Documentation
¶
Index ¶
- type Action
- type Annotation
- func (o *Annotation) First() (val string)
- func (o *Annotation) FirstBool() bool
- func (o *Annotation) Length() int
- func (o *Annotation) ToDomain() (domain *Domain)
- func (o *Annotation) ToError() (error *Error)
- func (o *Annotation) ToHeader() (header *Header)
- func (o *Annotation) With(val string) *Annotation
- type AnnotationKey
- type Comment
- type CommentDescription
- type Controller
- type Document
- func (o *Document) Acquire(path, cn string) (controller *Controller)
- func (o *Document) Export() (err error)
- func (o *Document) HyperLink(uri, mtd string) (path, link, name, based string)
- func (o *Document) Json() string
- func (o *Document) Load(path string) (err error)
- func (o *Document) LoadWithBody(body []byte) error
- func (o *Document) LoadWithJson(str string) error
- func (o *Document) MergeError(a, b []*Error) []*Error
- func (o *Document) MergeHeader(a, b []*Header) []*Header
- func (o *Document) Reflect() (err error)
- func (o *Document) Save(path string) (err error)
- func (o *Document) SaveRunner(path, pathJson string) (err error)
- func (o *Document) SetComment(c *Comment)
- func (o *Document) SortFields(entries []*Entry) []*Entry
- func (o *Document) SortResults(entries []*Entry, arr bool) template.HTML
- func (o *Document) WriteTo(path string, content string) (err error)
- type Domain
- type Entry
- type Error
- type Header
- type StructBodyType
- type StructPath
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Action ¶
type Action struct {
Controller *Controller `json:"-"`
Descriptions []*CommentDescription `json:"descriptions,omitempty"`
// Errors
// is a list for response, that define in any action comment like follows.
//
// // PostLogin
// // User login.
// //
// // @Error(4001, "payload error")
// // @Error(4002, "incorrect password")
// func (o *Controller) PostLogin(ctx iris.Context) {
// }
Errors []*Error `json:"errors,omitempty"`
ExportedBase string `json:"-"` // ../../
ExportedName string `json:"-"` // post.html
ExportedLink string `json:"-"` // user/login/post.html
ExportedPath string `json:"-"` // /data/sketch/docs/api/html/user/login/post.html
// File
// is a path. The Action defined in which file like follows.
//
// {
// "file": "/user/controller.go",
// ...
// }
File string `json:"file"`
Hash string `json:"hash"`
// Headers
// is a list for requests header, that define in any action comment.
//
// This is a sample in /data/sketch/app/controllers/user/controller.go`
// at type comment like follows.
//
// // Controller
// // user operation.
// //
// // @Header("Content-Type", "application/json")
// func (o *Controller) PostLogin(ctx iris.Context) {
// }
Headers []*Header `json:"headers,omitempty"`
Ignored bool `json:"ignored"`
// Line
// is the line number of the controller file that the action defined in.
Line int `json:"line"`
Name string `json:"name"`
// RequestBody
// use to send on a request. This reflected from struct instance.
RequestBody []*Entry `json:"request_body,omitempty"`
// RequestBodyStruct
// is a struct path that define in any action comment.
//
// Annotations accept @<Request|RequestList>.
//
// This is a sample in /data/sketch/app/controllers/user/controller.go`
// at type comment like follows.
//
// // Controller
// // user operation.
// //
// // @Request(app/logics/user/login.Request)
// // @Response(app/logics/user/login.Response)
// func (o *Controller) PostLogin(ctx iris.Context) {
// }
RequestBodyStruct StructPath `json:"request_body_struct,omitempty"`
// RequestBodyType
// is the request body type. It's depended on the request body
// annotation.
//
// - OBJECT
// - LIST
RequestBodyType StructBodyType `json:"request_body_type,omitempty"`
// RequestMethod
// is a http method that request send to the server such as GET, POST,
// DELETE, PUT, PATCH, OPTIONS, HEAD etc.
//
// Collect first word of the function name if not defined by annotation.
//
// Annotations accept @<Get|Post|Delete|Put|Patch|Options|Head|Any|Route>, Route
// in list is equal to Get, Any in list means this action accept all methods.
//
// Collect first letter: Post as request method.
//
// // PostLogin
// // send log in request.
// func (o *Controller) PostLogin(ctx iris.Context) {
// }
//
// Use annotation: Post as request method.
//
// // PostLogout
// // send log out request.
// //
// // @Post(/logout)
// func (o *Controller) PostLogout(ctx iris.Context) {
// }
RequestMethod string `json:"request_method"`
RequestSampleCode template.HTML `json:"-"`
// RequestUrl
// is the request url of the action. Parse from function name if not defined
// by annotation.
//
// Parse function name: /login.
//
// // PostLogin
// // send log in request.
// func (o *Controller) PostLogin(ctx iris.Context) {
// }
//
// Parse function name: /login/mobile.
//
// // PostLoginMobile
// // send log in request with mobile number.
// func (o *Controller) PostLoginMobile(ctx iris.Context) {
// }
//
// Use annotation: /logout.
//
// // PostLogout
// // send log out request.
// //
// // @Post(/logout)
// func (o *Controller) PostLogout(ctx iris.Context) {
// }
RequestUrl string `json:"request_url"`
// ResponseBody
// response result to client. This reflected from struct instance.
ResponseBody []*Entry `json:"response_body,omitempty"`
// ResponseBodyStruct
// is a struct path that define in any action comment.
//
// Annotations accept @<Response|ResponseList|ResponsePaging>.
//
// This is a sample in /data/sketch/app/controllers/user/controller.go`
// at type comment like follows.
//
// // Controller
// // user operation.
// //
// // @Request(app/logics/user/login.Request)
// // @Response(app/logics/user/login.Response)
// func (o *Controller) PostLogin(ctx iris.Context) {
// }
ResponseBodyStruct StructPath `json:"response_body_struct,omitempty"`
// ResponseBodyType
// is the request body type. It's depended on the response body
// annotation.
//
// - OBJECT
// - LIST
// - PAGING
ResponseBodyType StructBodyType `json:"response_body_type,omitempty"`
ResponseSampleCode template.HTML `json:"-"`
// Title
// is the title of the action. Keep function name as title if not defined.
//
// - User log in
Title string `json:"title"`
// contains filtered or unexported fields
}
Action is a component that store scanned action info.
func NewAction ¶
NewAction creates a new Action with given name.
action := NewAction("PostUserLogin")
func (*Action) SetComment ¶
SetComment set comment to parse definitions.
type Annotation ¶
type Annotation struct {
Key AnnotationKey
Values []string
}
Annotation is a component that parsed from comment. formater like follows:
@Key @Key() @Key("value") @Key("value", "value-2")
func NewAnnotation ¶
func NewAnnotation(key string) *Annotation
NewAnnotation creates an annotation component.
func (*Annotation) First ¶
func (o *Annotation) First() (val string)
First returns the first value of the annotation.
func (*Annotation) FirstBool ¶
func (o *Annotation) FirstBool() bool
FirstBool returns the first value of the annotation as boolean.
func (*Annotation) Length ¶
func (o *Annotation) Length() int
Length returns the length of the values.
func (*Annotation) ToDomain ¶
func (o *Annotation) ToDomain() (domain *Domain)
ToDomain converts the annotation values to Domain component.
func (*Annotation) ToError ¶
func (o *Annotation) ToError() (error *Error)
ToError converts the annotation values to Error component.
func (*Annotation) ToHeader ¶
func (o *Annotation) ToHeader() (header *Header)
ToHeader converts the annotation values to Header component.
func (*Annotation) With ¶
func (o *Annotation) With(val string) *Annotation
With adds the value to the annotation.
type AnnotationKey ¶
type AnnotationKey string
AnnotationKey is a type name of an annotation with ignore cases.
const ( AnnotationKeyDomain AnnotationKey = "DOMAIN" // <D> @Domain("http://example.com", "Production") AnnotationKeyError AnnotationKey = "ERROR" // <A|C|D> @Error(400, "BAD_REQUEST", "Bad Request") AnnotationKeyHeader AnnotationKey = "HEADER" // <A|C|D> @Header("Content-Type", "application/json", "Request content type") AnnotationKeyIgnore AnnotationKey = "IGNORE" // <A|C> @Ignore, @Ignore(), @Ignore(true), @Ignore(false) AnnotationKeyRequest AnnotationKey = "REQUEST" // <A> @Request("app/logics/user/login.Request") AnnotationKeyRequestList AnnotationKey = "REQUESTLIST" // <A> @RequestList("app/logics/user/search.Request") AnnotationKeyResponse AnnotationKey = "RESPONSE" // <A> @Response("/v1/user/login") AnnotationKeyResponseList AnnotationKey = "RESPONSELIST" // <A> @ResponseList("/v1/user/search.Response") AnnotationKeyResponsePaging AnnotationKey = "RESPONSEPAGING" // <A> @ResponsePaging("/v1/user/search.Response") AnnotationKeyRoute AnnotationKey = "ROUTE" // <A> @Route("/v1/user/login") AnnotationKeyRoutePrefix AnnotationKey = "ROUTEPREFIX" // <C> @RoutePrefix("/v1/user") )
func NewAnnotationKey ¶
func NewAnnotationKey(key string) AnnotationKey
NewAnnotationKey creates a new annotation key.
func (AnnotationKey) Is ¶
func (o AnnotationKey) Is(key AnnotationKey) bool
Is compare the give annotation key with current.
func (AnnotationKey) IsDomain ¶
func (o AnnotationKey) IsDomain() bool
IsDomain check whether the current annotation key is domain.
func (AnnotationKey) IsError ¶
func (o AnnotationKey) IsError() bool
IsError check whether the current annotation key is error.
func (AnnotationKey) IsHeader ¶
func (o AnnotationKey) IsHeader() bool
IsHeader check whether the current annotation key is header.
type Comment ¶
type Comment struct {
Annotations []*Annotation `json:"annotations,omitempty"`
Descriptions []*CommentDescription `json:"descriptions,omitempty"`
Title string `json:"title,omitempty"`
}
Comment is a component that represents a comment of a controller or an action or document.
type CommentDescription ¶
type CommentDescription struct {
Text []template.HTML `json:"text,omitempty"`
Codes []template.HTML `json:"codes,omitempty"`
}
CommentDescription is a component that represents the description of comment.
func NewCommentDescription ¶
func NewCommentDescription() *CommentDescription
NewCommentDescription creates a new instance of CommentDescription.
type Controller ¶
type Controller struct {
// Actions
// is a list of actions that the controller defined, These actions scanned
// from controller directory, such as /data/sketch/app/controllers/controller.go.
Actions []*Action `json:"actions,omitempty"`
// Descriptions
// scanned from Controller comment.
Descriptions []*CommentDescription `json:"descriptions,omitempty"`
// Document
// is a component that link to Document.
Document *Document `json:"-"`
// Errors
// is a list for response status, that define in any controller files. All
// actions in the controller contain the same errors.
//
// This is a sample in /data/sketch/app/controllers/user/controller.go`
// at type comment like follows.
//
// // Controller
// // user operation.
// //
// // @Error(401, "not logged in")
// // @Error(403, "access denied")
// type Controller struct {
// }
Errors []*Error `json:"errors,omitempty"`
// File
// remark the file path of the controller.
File string `json:"file"`
// Headers
// is a list for requests header, that define in any controller files. All
// actions in the controller contain the same headers.
//
// This is a sample in /data/sketch/app/controllers/user/controller.go`
// at type comment like follows.
//
// // Controller
// // user operation.
// //
// // @Header("Content-Type", "application/json")
// type Controller struct {
// }
Headers []*Header `json:"headers,omitempty"`
// Ignored
// whether the controller is ignored when export as documents.
Ignored bool `json:"ignored"`
// Line
// remark the line of the controller file.
Line int `json:"line"`
// Name
// is a name of the controller that collect from type comment. This collected
// in preview.
Name string `json:"name"`
// RoutePrefix
// define the route prefix of the controller. All actions uri in the controller
// start with it.
//
// This is a sample in /data/sketch/app/controllers/user/controller.go
// at type comment like follows.
//
// // Controller
// // user operation.
// //
// // @RoutePrefix(/user)
// type Controller struct {
// }
RoutePrefix string `json:"route_prefix"`
// Title
// is a name of the controller that collect from type comment. This collected in preview
// comment should be `user operation`.
//
// - user operation
Title string `json:"title"`
}
Controller is a component that store controller scanned info.
func NewController ¶
func NewController(name string) *Controller
NewController create a new controller instance.
func (*Controller) Export ¶
func (o *Controller) Export() (err error)
Export actions document in the controller.
func (*Controller) Reflect ¶
func (o *Controller) Reflect() (err error)
Reflect call reflection to generate request and response structs.
func (*Controller) SetComment ¶
func (o *Controller) SetComment(c *Comment)
SetComment set comment to parse definitions.
type Document ¶
type Document struct {
// AbsDir
// is an absolute path of the application. It's read from an option value.
//
// Convert base-dir option value to absolute path.
//
// Usage:
// ./console gen:doc --base-dir=./
AbsDir string `json:"abs_dir"`
// ControllerPath
// root controller files location.
//
// - app/controllers
ControllerPath string `json:"controller_path"`
// Controllers
// scanned from controller directory, such as `/data/sketch/app/controllers`.
Controllers map[string]*Controller `json:"controllers,omitempty"`
// Descriptions
// scanned from comment in root controllers package.
Descriptions []*CommentDescription `json:"descriptions,omitempty"`
// Domain
// is a domain value for different environments.
//
// - http://api.example.com
Domain string `json:"domain,omitempty"`
// Domains
// is a list for domains that define in root controller package comment
// like follows.
//
// // Package controllers
// // Your Application Service.
// //
// // @Domain("http://test.example.com", "Testing")
// // @Domain("https://api.example.com", "Production")
// package controllers
Domains []*Domain `json:"domains,omitempty"`
// Headers
// is a list for request or response that define in root controller package
// comment like follows.
//
// // Package controllers
// // Your Application Service.
// //
// // @Error(400, "bad request")
// package controllers
Errors []*Error `json:"errors,omitempty"`
// Ext
// is an extension name of a document file. It's read from an option.
//
// Usage:
// ./example --output-format=md
//
// Accepts:
// - md - README.md, post.md
// - html - index.html, post.html
Ext base.Format `json:"ext"`
// Headers
// is a list for requests header, that define in doc.go in root controller
// directory. All actions contain the same headers.
//
// This is a sample that must defined in /data/sketch/app/controllers/doc.go`
// at package comment like follows.
//
// // Package controllers.
// //
// // @Header("Content-Type", "application/json")
// package controllers
Headers []*Header `json:"headers,omitempty"`
// ModuleName
// is scanned from go.mod file of the application.
//
// Source: /data/sketch/go.mod
//
// Code:
//
// {
// "module_name": "payment",
// ...
// }
ModuleName string `json:"module_name"`
// OutputPath
// is a relative path in application. It's read from an option when command
// executed. All documents will be generated and exported to here.
//
// Usage:
//
// ./console gen:doc --output-path=docs/api
//
// Code:
//
// {
// "output_path": "docs/api",
// ...
// }
OutputPath string `json:"output_path"`
// Scripts
// store command runner scripts.
//
// [
// "go run main.go gen:doc",
// `--base-dir="./"`,
// `--controller-path="app/controllers"`,
// `--output-format="html"`,
// `--output-path="docs/api"`
// ]
Scripts []template.HTML `json:"scripts"`
// Time
// for the command last executed at.
//
// Code:
//
// {
// "time": "2024/05/01 09:10",
// ...
// }
Time string `json:"time"`
// Title
// is the application name.
//
// Code:
//
// {
// "title": "Your Application Service",
// ...
// }
Title string `json:"title"`
ExportedBase string `json:"-"`
ExportedLink string `json:"-"`
ExportedPath string `json:"-"`
}
Document is a component that store application scanned info.
func (*Document) Acquire ¶
func (o *Document) Acquire(path, cn string) (controller *Controller)
Acquire a controller by path and name. Create new if not found.
.Acquire("/user/controller.go", "Controller")
func (*Document) HyperLink ¶
HyperLink generate request uri as file path and hyperlink.
.HyperLink("/", "")
.HyperLink("/user/login", "POST")
func (*Document) Load ¶
Load data from given file that formatted as json string.
.Load("main.json")
.Load("/data/sketch/docs/api/.builder/main.json")
func (*Document) LoadWithBody ¶
LoadWithBody fields from given json body.
func (*Document) LoadWithJson ¶
LoadWithJson fields from given json string.
func (*Document) MergeError ¶
MergeError merge error annotation.
func (*Document) MergeHeader ¶
MergeHeader merge header annotations with unique key.
func (*Document) Save ¶
Save scanned data as json string.
.Save("/data/sketch/docs/api/.builder/main.json")
func (*Document) SaveRunner ¶
SaveRunner creates a runnable script file (main.go) to given path.
func (*Document) SetComment ¶
SetComment set comment to parse definitions.
func (*Document) SortFields ¶
SortFields sort fields by name and required.
func (*Document) SortResults ¶
SortResults returns the given entries as json string.
type Domain ¶
Domain is a component that is responsible for generating documentation.
Domains are collected from the annotations. It's only allowed to define in root controllers package comment like follow.
// Package controllers
// Your Application Service.
//
// @Domain("http://api.example.com")
// @Domain("https://api.example.com", "Production")
package controllers
type Entry ¶
type Entry struct {
Child []*Entry `json:"child"`
Condition string `json:"condition,omitempty"`
Description template.HTML `json:"desc,omitempty"`
IsArray bool `json:"is_array"`
IsStruct bool `json:"is_struct"`
Label string `json:"label,omitempty"`
Level []int `json:"level"`
Mock any `json:"mock"`
Name string `json:"name"`
Required bool `json:"required"`
Type string `json:"type"`
}
Entry is a component for request and response field definition.
type Error ¶
type Error struct {
Code any `json:"code"`
Message string `json:"message"`
Description string `json:"description"`
}
Error is a component that represents the error code.
Errors are collected from the annotations. It's defined in comment for Controller struct, Action function, root controllers package.
- @Error(401, "Unauthorized")
- @Error(403, "Forbidden", "Token expired or no access on this resource")
type Header ¶
type Header struct {
Key string `json:"key"`
Value string `json:"value"`
Label string `json:"label"`
}
Header is a request or response header component.
Headers are collected from the annotations. It's defined in comment for Controller struct, Action function, root controllers package.
- @Header("Authorization", "Bearer token")
- @Header("Authorization", "Bearer token", "JWT token string")
type StructBodyType ¶
type StructBodyType string
StructBodyType is a type name that represents the type of the request or response struct.
const ( StructBodyTypeObject StructBodyType = "Object" StructBodyTypeList StructBodyType = "List" StructBodyTypePaging StructBodyType = "Paging" )
func (StructBodyType) Array ¶
func (o StructBodyType) Array() bool
Array returns true if the type is an array.
type StructPath ¶
type StructPath string
StructPath is a type name that represents a request or response. It's scanned from action comment like follows.
- @Request(app/logics/user/login.Request)
- @RequestList(app/logics/user/search.Request)
- @Response(app/logics/user/login.Response)
- @ResponseList(app/logics/user/search.Response)
- @ResponsePaging(app/logics/user/search.Response)
func (StructPath) Scan ¶
func (o StructPath) Scan() (fields []*Entry, err error)
Scan struct fields by name that registered to registry.
func (StructPath) String ¶
func (o StructPath) String() string
String returns a struct name with package like follows.
- app/logics/user/login.Request
- app/logics/user/login.Response