data

package
v0.0.9 Latest Latest
Warning

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

 Go to latest Published: Jul 5, 2024 License: Apache-2.0 Imports: 14 Imported by: 0

Documentation

Index

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 

func NewAction(name string) *Action

NewAction creates a new Action with given name. 

action := NewAction("PostUserLogin")

func (*Action) Default 

func (o *Action) Default()

func (*Action) Export 

func (o *Action) Export() (err error)

Export action document that formatted as markdown.

func (*Action) Reflect 

func (o *Action) Reflect() (err error)

Reflect use reflection to get the struct fields definition.

func (*Action) SetComment 

func (o *Action) SetComment(c *Comment)

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.

func NewComment 

func NewComment() *Comment

NewComment creates a new comment.

func (*Comment) Parse 

func (o *Comment) Parse(lines []string, prefix string) *Comment

Parse parses the comment line by line into the component fields.

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

func (o *Controller) Add(action *Action)

Add a new action to Actions.

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 New 

func New() *Document

New creates a new Document instance.

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

func (o *Document) Export() (err error)

Export document files that formatted as markdown. 

func (o *Document) HyperLink(uri, mtd string) (path, link, name, based string)

HyperLink generate request uri as file path and hyperlink. 

.HyperLink("/", "")
.HyperLink("/user/login", "POST")

func (*Document) Json 

func (o *Document) Json() string

Json converts data to json string.

func (*Document) Load 

func (o *Document) Load(path string) (err error)

Load data from given file that formatted as json string. 

.Load("main.json")
.Load("/data/sketch/docs/api/.builder/main.json")

func (*Document) LoadWithBody 

func (o *Document) LoadWithBody(body []byte) error

LoadWithBody fields from given json body.

func (*Document) LoadWithJson 

func (o *Document) LoadWithJson(str string) error

LoadWithJson fields from given json string.

func (*Document) MergeError 

func (o *Document) MergeError(a, b []*Error) []*Error

MergeError merge error annotation.

func (*Document) MergeHeader 

func (o *Document) MergeHeader(a, b []*Header) []*Header

MergeHeader merge header annotations with unique key.

func (*Document) Reflect 

func (o *Document) Reflect() (err error)

Reflect call reflection to generate request and response structs.

func (*Document) Save 

func (o *Document) Save(path string) (err error)

Save scanned data as json string. 

.Save("/data/sketch/docs/api/.builder/main.json")

func (*Document) SaveRunner 

func (o *Document) SaveRunner(path, pathJson string) (err error)

SaveRunner creates a runnable script file (main.go) to given path.

func (*Document) SetComment 

func (o *Document) SetComment(c *Comment)

SetComment set comment to parse definitions.

func (*Document) SortFields 

func (o *Document) SortFields(entries []*Entry) []*Entry

SortFields sort fields by name and required.

func (*Document) SortResults 

func (o *Document) SortResults(entries []*Entry, arr bool) template.HTML

SortResults returns the given entries as json string.

func (*Document) WriteTo 

func (o *Document) WriteTo(path string, content string) (err error)

WriteTo writes the given content to the given path. 

.WriteTo("/data/sketch/docs/api/.builder/main.json", "...")
.WriteTo("/data/sketch/docs/api/md/get.md", "...")
.WriteTo("/data/sketch/docs/api/md/user/login/post.md", "...")

type Domain 

type Domain struct {
	Host  string `json:"host"`
	Label string `json:"label"`
}

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.

func NewEntry 

func NewEntry(field *ref.Field, level int) *Entry

NewEntry creates a new Entry with reflected field from struct.

func (*Entry) With 

func (o *Entry) With(field *ref.Field) *Entry

With reflected field of a struct to initialize.

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

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.