feat(goctl): Add api parser (#2585)

tools/goctl/pkg/parser/api/format/testdata/expected_service.api

@@ -0,0 +1,36 @@
+// server foo
+@server ( // server
+    // key-value form
+    key1:   value1
+    key2:   value2
+    jwt:    Auth // enable jwt
+    prefix: /v1 // the route prefix
+)
+// service foo
+service foo { // foo
+    // example1
+    @doc "example1"
+    @handler example1 // handler declare
+    get /path/example1 // no body
+
+    @doc ( // doc group
+        key1:   "value1"
+        key11:  "value11"
+        key111: "value111"
+    )
+    @handler example2 // handler example2
+    get /path/example2/:id // path arg
+
+    @doc "example3"
+    @handler example3
+    get /path/example3/:id (Foo) // no response
+
+    @doc "example4"
+    @handler example4
+    post /path/example4/a-b returns (Foo) // no request
+
+    @doc "example5"
+    @handler example5
+    // example5
+    post /path/example5/a-b (Foo) returns (Bar) // do not comment between path and body
+}

tools/goctl/pkg/parser/api/format/testdata/expected_type_struct_group.api

@@ -0,0 +1,37 @@
+/*aa*/
+type (
+    /*bb*/
+    T /*cc*/ { // T.bg
+        // Name head1
+        /*Name head2*/
+        Name string `json:"name"` // name
+        Age  int    `json:"age"` // age
+        Extra
+        Address string
+        Hobby []{
+            Name string // hobby.name
+            Rate string
+        } `json:"hobby"` // hobby
+        Child { // child.bg
+            Name     string `json:"name"` // child.name
+            Gender   int    `json:"gender"` // child.gender
+            Birthday string `json:"birthday"` // child.birthday
+            Desc     string // son.desc
+            Son { // son.bg
+                Name     string `json:"name"` // son.name
+                Gender   int    `json:"gender"` // son.gender
+                Birthday string `json:"birthday"` // son.birthday
+                Desc     string // son.desc
+                Hobby []{
+                    Name        string // hobby.name
+                    Description string
+                    // Map
+                    Map map[string]{
+                        Name string `json:"name"`
+                        Age  string `json:"age"`
+                    } `json:"map"`
+                } `json:"hobby"` // hobby
+            } // son.end
+        } // child.end
+    } // T.end
+)

tools/goctl/pkg/parser/api/format/testdata/expected_type_struct_lit.api

@@ -0,0 +1,34 @@
+/*aa*/
+type /*bb*/ T /*cc*/ { // T.bg
+    // Name head1
+    /*Name head2*/
+    Name string `json:"name"` // name
+    Age  int    `json:"age"` // age
+    Extra
+    Address string
+    Hobby []{
+        Name string // hobby.name
+        Rate string
+    } `json:"hobby"` // hobby
+    Child { // child.bg
+        Name     string `json:"name"` // child.name
+        Gender   int    `json:"gender"` // child.gender
+        Birthday string `json:"birthday"` // child.birthday
+        Desc     string // son.desc
+        Son { // son.bg
+            Name     string `json:"name"` // son.name
+            Gender   int    `json:"gender"` // son.gender
+            Birthday string `json:"birthday"` // son.birthday
+            Desc     string // son.desc
+            Hobby []{
+                Name        string // hobby.name
+                Description string
+                // Map
+                Map map[string]{
+                    Name string `json:"name"`
+                    Age  string `json:"age"`
+                } `json:"map"`
+            } `json:"hobby"` // hobby
+        } // son.end
+    } // child.end
+} // T.end

tools/goctl/pkg/parser/api/format/testdata/test_format.api

@@ -0,0 +1,154 @@
+syntax = "v1"
+
+import "example_base1.api"
+
+import (
+	"example_base2.api"
+)
+
+info (
+	title:   "type title here"
+	desc:    "type desc here"
+	author:  "type author here"
+	email:   "type email here"
+	version: "type version here"
+)
+
+type GetFormReq {
+	Name    string   `form:"name"`
+	Age     int      `form:"age"`
+	Hobbits []string `form:"hobbits"`
+	Any     any      `form:"any"`
+}
+
+type GetFormREsp {
+	Name    string   `json:"name"`
+	Age     int      `json:"age"`
+	Hobbits []string `json:"hobbits"`
+}
+
+type (
+	PostFormReq {
+		Name    string   `form:"name"`
+		Age     int      `form:"age"`
+		Hobbits []string `form:"hobbits"`
+	}
+	PostFormResp {
+		Name    string   `json:"name"`
+		Age     int      `json:"age"`
+		Hobbits []string `json:"hobbits"`
+	}
+)
+
+type (
+	PostJsonReq {
+		Name    string   `json:"name"`
+		Age     int      `json:"age"`
+		Hobbits []string `json:"hobbits"`
+	}
+	PostJsonResp {
+		Name    string            `json:"name"`
+		Age     int               `json:"age"`
+		Hobbits []string          `json:"hobbits"`
+		Extra   map[string]string `json:"extra"`
+		Data    interface{}       `json:"data"`
+	}
+)
+
+type (
+	PostPathReq {
+		Id string `path:"id"`
+	}
+	PostPathResp {
+		Name    string            `json:"name"`
+		Age     int               `json:"age"`
+		Hobbits []string          `json:"hobbits"`
+		Extra   map[string]string `json:"extra"`
+		Data    interface{}       `json:"data"`
+	}
+)
+
+type (
+	DemoOfArrayReq {
+		In string `json:"in"`
+	}
+	DemoOfArrayResp {
+		Out string `json:"out"`
+	}
+)
+
+type (
+	Nest {
+		Name string `json:"name"`
+	}
+	NestDemoReq {
+		Nest *Nest `json:"nest"`
+	}
+	NestDemoResp {
+		Nest []*Nest `json:"nest"`
+	}
+)
+
+@server (
+	group: form
+)
+service example {
+	@handler getForm
+	get /example/form (GetFormReq) returns (GetFormREsp)
+
+	@handler postForm
+	post /example/form (PostFormReq) returns (PostFormResp)
+}
+
+@server (
+	group: json
+	jwt:   Auth
+)
+service example {
+	@doc "json demo"
+	@handler postJson
+	post /example/json (PostJsonReq) returns (PostJsonResp)
+}
+
+@server (
+	group:      path
+	middleware: Path
+	prefix:     /v1/v2
+)
+service example {
+	@doc (
+		desc: "path demo"
+	)
+	@handler postPath
+	post /example/path (PostPathReq) returns (PostPathResp)
+}
+
+@server (
+	group:  array
+	prefix: /array
+)
+service example {
+	@doc (
+		desc: "array response demo"
+	)
+	@handler getArray
+	post /example/array (DemoOfArrayReq) returns ([]DemoOfArrayResp)
+
+	@doc (
+		desc: "array pointer response demo"
+	)
+	@handler getArrayPointer
+	post /example/array/pointer (DemoOfArrayReq) returns ([]*DemoOfArrayResp)
+
+	@doc (
+		desc: "array base response demo"
+	)
+	@handler getArrayBase
+	post /example/array/pointer (DemoOfArrayReq) returns ([]string)
+}
+
+service example {
+	@handler nestDemo
+	post /example/nest (NestDemoReq) returns (NestDemoResp)
+}
+

tools/goctl/pkg/parser/api/format/testdata/test_service.api

@@ -0,0 +1,35 @@
+// server foo
+@server(// server
+// key-value form
+key1:value1
+key2:value2
+jwt:Auth // enable jwt
+prefix: /v1 // the route prefix
+)
+// service foo
+service foo{// foo
+    // example1
+    @doc "example1"
+    @handler example1 // handler declare
+    get /path/example1// no body
+@doc( // doc group
+key1:"value1"
+key11:"value11"
+key111:"value111"
+)
+    @handler example2 // handler example2
+get /path/example2/:id// path arg
+    @doc
+    "example3"
+    @handler
+example3
+    get     /path/example3/:id
+    ( Foo )// no response
+    @doc "example4"
+    @handler example4
+    post /path/example4/a-b returns ( Foo )// no request
+    @doc "example5"
+    @handler example5
+    // example5
+    post        /path/example5/a-b ( Foo ) returns ( Bar ) // do not comment between path and body
+}

tools/goctl/pkg/parser/api/format/testdata/test_type_struct_group.api

@@ -0,0 +1,34 @@
+/*aa*/type (
+/*bb*/T /*cc*/{// T.bg
+// Name head1
+/*Name head2*/Name string `json:"name"`// name
+Age int `json:"age"` // age
+Extra
+Address string
+Hobby []{
+Name string // hobby.name
+Rate string
+} `json:"hobby"` // hobby
+Child {// child.bg
+Name string `json:"name"`// child.name
+Gender int `json:"gender"`// child.gender
+Birthday string `json:"birthday"`// child.birthday
+Desc string // son.desc
+Son {// son.bg
+Name string `json:"name"`// son.name
+Gender int `json:"gender"`// son.gender
+Birthday string `json:"birthday"`// son.birthday
+Desc string // son.desc
+Hobby []{
+    Name string // hobby.name
+    Description string
+    // Map
+    Map map[string]{
+Name string `json:"name"`
+Age string `json:"age"`
+}`json:"map"`
+} `json:"hobby"` // hobby
+}// son.end
+}// child.end
+}// T.end
+)

tools/goctl/pkg/parser/api/format/testdata/test_type_struct_lit.api

@@ -0,0 +1,32 @@
+/*aa*/type /*bb*/T /*cc*/{// T.bg
+// Name head1
+/*Name head2*/Name string `json:"name"`// name
+Age int `json:"age"` // age
+Extra
+Address string
+Hobby []{
+Name string // hobby.name
+Rate string
+} `json:"hobby"` // hobby
+Child {// child.bg
+Name string `json:"name"`// child.name
+Gender int `json:"gender"`// child.gender
+Birthday string `json:"birthday"`// child.birthday
+Desc string // son.desc
+Son {// son.bg
+Name string `json:"name"`// son.name
+Gender int `json:"gender"`// son.gender
+Birthday string `json:"birthday"`// son.birthday
+Desc string // son.desc
+Hobby []{
+    Name string // hobby.name
+    Description string
+    // Map
+    Map map[string]{
+Name string `json:"name"`
+Age string `json:"age"`
+}`json:"map"`
+} `json:"hobby"` // hobby
+}// son.end
+}// child.end
+}// T.end