feat: support gen mocks data, mock server

Author: alovn

.vscode/launch.json

@@ -5,17 +5,31 @@
     "version": "0.2.0",
     "configurations": [
         {
-            "name": "Launch file",
+            "name": "Generate Docs and Mocks",
             "type": "go",
             "request": "launch",
             "mode": "debug",
-            "cwd": "${workspaceRoot}",
+            "cwd": "${workspaceRoot}/examples",
             "program": "${workspaceFolder}/main.go",
             "args": [
-                "--dir", "examples/svc-user,examples/common",
-                "--output", "examples/docs",
+                "--dir", "svc-user,common",
+                "--output", "docs",
                 "--template", "markdown",
+                "--gen-mocks"
             ]
-        }
+        },
+        {
+            "name": "Mock Server",
+            "type": "go",
+            "request": "launch",
+            "mode": "debug",
+            "cwd": "${workspaceRoot}/examples",
+            "program": "${workspaceFolder}/main.go",
+            "args": [
+                "mock",
+                "--dir", "./docs/mocks",
+                "--listen", "localhost:8001"
+            ]
+        },
     ]
 }

README.md

@@ -1,6 +1,6 @@
 # apidocgen
 
-apidocgen is a tool for Go to generate apis markdown docs.
+apidocgen is a tool for Go to generate apis markdown docs and mocks.
 
 ## Install
 
@@ -12,44 +12,40 @@ go install github.com/alovn/apidocgen@latest
 
 ```bash
 $ apidocgen --help
-apidocgen is a tool for Go to generate apis markdown docs.
+apidocgen is a tool for Go to generate apis markdown docs and mocks. For example:
 
-Usage:
-  apidocgen --dir= --excludes= --output= --output-index= --template= --single
-
-Flags:
-        --dir:          Search apis dir, comma separated, default .
-        --excludes:     Exclude directories and files when searching, comma separated
-        --output:       Generate markdown files dir, default ./docs/
-        --output-index: Generate index file name.
-        --template:     Template name or custom template directory, built-in includes markdown and apidocs, default markdown.
-        --single:       Generate a single markdown file.
-```
-
-built-in templates include `markdown` and `apidocs`, default is `markdown`.
+apidocgen --dir= --excludes= --output= --output-index= --template= --single --gen-mocks
+apidocgen --mock --mock-listen=:8001
+apidocgen mock --data= --listen=
 
-run the command in the go module directory.
-
-```bash
-cd your-api-service-dir
-apidocgen \
-    --dir=svc-user,common \
-    --output=./docs
+Usage:
+  apidocgen [flags]
+  apidocgen [command]
 
-apidocgen \
-    --dir=svc-user,common \
-    --template=apidocs \
-    --output=./docs
+Available Commands:
+  help        Help about any command
+  mock        
 
-apidocgen --output-index=index.md //generate index.md
-apidocgen --output-index=@{service}.md //generate index file name by your @service comment, example: svc-user.md.
+Flags:
+      --dir string            Search apis dir, comma separated (default ".")
+      --excludes string       Exclude directories and files when searching, comma separated
+      --gen-mocks             Is generate the mock files
+  -h, --help                  help for apidocgen
+      --mock-listen string    Mock Server listen address (default "localhost:8001")
+      --mock                  Serve a mock server
+      --output string         Generate markdown files dir (default "./docs/")
+      --output-index string   Generate index file name
+      --single                Is generate a single doc
+      --template string       Template name or custom template directory, built-in includes markdown and apidocs
+
+Use "apidocgen [command] --help" for more information about a command.
 ```
 
 ## Template
 
-The built-in includes `markdown` and `apidocs`.
+The built-in templates include `markdown` and `apidocs`, default is `markdown`.
 
-The built-in template `apidocs` is the template for generate website [apidocs](https://github.com/alovn/apidocs).
+The template `apidocs` is the template for generate website [apidocs](https://github.com/alovn/apidocs).
 
 You can also use the custom template:
 
@@ -96,8 +92,8 @@ apidocgen supported any web frameworks. here are an example using [bytego](https
     //@accept json
     //@format json
     //@request LoginRequest
-    //@response 200 common.Response{code=0,msg="success",data=LoginResponse} "登录成功返回数据"
-    //@response 200 common.Response{code=10020,msg="password_error"} "密码错误"
+    //@response 200 common.Response{code=0,msg="success",data=LoginResponse} "success description" //mock
+    //@response 200 common.Response{code=10020,msg="password_error"} "error description"
     //@author alovn
     func (c *Controller) Login(c *bytego.Ctx) {
         //bind LoginRequest
@@ -128,7 +124,7 @@ annotation|description|example
 --|--|--
 service|Required, the service's identification|@service svc-user
 baseurl|The base url of api|@baseurl /
-group|The group of service|@group account
+group|The group of service, add it at api comment or at the head of file comment.|@group account
 title|The title of service, group and api|@title UserService
 desc|The description of service, group and api|@desc xxx
 api|The http api handler|@api POST /account/register
@@ -186,6 +182,7 @@ deprecated|Mark api as deprecated.|@deprecated
     import (
         "common"
     )
+
     //response 200 common.Response{code=0,data=User} "success description"
     ```
 
@@ -197,3 +194,40 @@ deprecated|Mark api as deprecated.|@deprecated
         Name string `json:"name" example:"user name"`
     } //User Infomation
     ```
+
+## Mock
+
+1. generate apis mocks files. add `//mock` at the end of `response`, default use first.
+
+    ```go
+    //response 200 Response{code=0,data=[]User} "success description" //mock
+    ```
+
+     generate apis mocks files, default generated in the directory `./docs/mocks`.
+
+    ```bash
+    apidocgen --dir=common,svc-user --gen-mocks
+    ```
+
+2. serve the mock server from source code.
+
+    ```bash
+    apidocgen --dir=common,svc-user --mock --mock-listen=:8001
+    ```
+
+3. serve the mock server from generated mock files.
+
+    ```bash
+    apidocgen mock --data=./mocks --listen=:8001
+    ```
+
+    ```bash
+    $ curl -X POST -d "" localhost:8001/user/account/login   
+    {
+      "code": 0,
+      "data": {
+        "welcome_msg": "string"
+      },
+      "msg": "success"
+    }
+    ```

cmd/mock.go

@@ -0,0 +1,40 @@
+/*
+Copyright © 2022 alovn <[email protected]>
+
+*/
+package cmd
+
+import (
+	"log"
+
+	"github.com/alovn/apidocgen/mock"
+	"github.com/spf13/cobra"
+)
+
+var (
+	mockDataDir string
+	mockListen  string
+)
+
+// mockCmd represents the mock command
+var mockCmd = &cobra.Command{
+	Use: "mock",
+	Long: `Serve a mock serve with generated mock files. For example:
+
+apidocgen mock --data=./docs/mocks --listen=localhost:8001`,
+	Run: func(cmd *cobra.Command, args []string) {
+		mockServer := mock.New(mockListen)
+		if err := mockServer.InitFiles(mockDataDir); err != nil {
+			log.Fatal(err)
+		}
+		if err := mockServer.Serve(); err != nil {
+			log.Fatal(err)
+		}
+	},
+}
+
+func init() {
+	rootCmd.AddCommand(mockCmd)
+	mockCmd.Flags().StringVar(&mockDataDir, "data", "./docs/mocks/", "mocks data directory.")
+	mockCmd.Flags().StringVar(&mockListen, "listen", "localhost:8001", "mock server listen address.")
+}

cmd/root.go

@@ -0,0 +1,73 @@
+/*
+Copyright © 2022 alovn <[email protected]>
+
+*/
+package cmd
+
+import (
+	"log"
+	"os"
+
+	"github.com/alovn/apidocgen/gen"
+	"github.com/spf13/cobra"
+)
+
+var (
+	searchDir        string
+	outputDir        string
+	outputIndexName  string
+	templateDir      string
+	excludesDir      string
+	isSingle         bool
+	isGenMocks       bool
+	isMockServer     bool
+	mockServerListen string
+)
+
+// rootCmd represents the base command when called without any subcommands
+var rootCmd = &cobra.Command{
+	Use: "apidocgen",
+	Long: `apidocgen is a tool for Go to generate apis markdown docs and mocks. For example:
+
+apidocgen --dir= --excludes= --output= --output-index= --template= --single --gen-mocks
+apidocgen --mock --mock-listen=:8001
+apidocgen mock --data= --listen=`,
+	CompletionOptions: cobra.CompletionOptions{
+		DisableDefaultCmd: true,
+	},
+	Run: func(cmd *cobra.Command, args []string) {
+		g := gen.New(&gen.Config{
+			SearchDir:        searchDir,
+			OutputDir:        outputDir,
+			OutputIndexName:  outputIndexName,
+			TemplateDir:      templateDir,
+			ExcludesDir:      excludesDir,
+			IsGenSingleFile:  isSingle,
+			IsGenMocks:       isGenMocks,
+			IsMockServer:     isMockServer,
+			MockServerListen: mockServerListen,
+		})
+		if err := g.Build(); err != nil {
+			log.Fatal(err)
+		}
+	},
+}
+
+func Execute() {
+	err := rootCmd.Execute()
+	if err != nil {
+		os.Exit(1)
+	}
+}
+
+func init() {
+	rootCmd.Flags().StringVar(&searchDir, "dir", ".", "Search apis dir, comma separated")
+	rootCmd.Flags().StringVar(&outputDir, "output", "./docs/", "Generate markdown files dir")
+	rootCmd.Flags().StringVar(&outputIndexName, "output-index", "", "Generate index file name")
+	rootCmd.Flags().StringVar(&templateDir, "template", "", "Template name or custom template directory, built-in includes markdown and apidocs")
+	rootCmd.Flags().StringVar(&excludesDir, "excludes", "", "Exclude directories and files when searching, comma separated")
+	rootCmd.Flags().BoolVar(&isSingle, "single", false, "Is generate a single doc")
+	rootCmd.Flags().BoolVar(&isGenMocks, "gen-mocks", false, "Is generate the mock files")
+	rootCmd.Flags().BoolVar(&isMockServer, "mock", false, "Serve a mock server")
+	rootCmd.Flags().StringVar(&mockServerListen, "mock-listen", "localhost:8001", "Mock Server listen address")
+}

examples/docs/apis-demo.md

@@ -157,44 +157,44 @@ __id__|_param_|int64|false|||DemoID
 _body_:
 
 ```xml
-<request> //object(handler.DemoXMLRequest), XML测试请求对象
-  <id>0</id> //int64, DemoID
+<request>  //object(handler.DemoXMLRequest), XML测试请求对象
+  <id>0</id>  //int64, DemoID
 </request>
 ```
 
 __Response__:
 
 ```xml
 //StatusCode: 200 
-<response> //object(common.Response), 通用返回结果
-  <code>0</code> //int, 返回状态码
-  <demo> //object(handler.DemoXMLResponse), XML测试返回对象
-    <address>string</address> //string, 地址信息
-    <city_id>0</city_id> //int64, 城市ID
-    <id>0</id> //int64, 地址ID
+<response>  //object(common.Response), 通用返回结果
+  <code>0</code>  //int, 返回状态码
+  <demo>  //object(handler.DemoXMLResponse), XML测试返回对象
+    <address>string</address>  //string, 地址信息
+    <city_id>0</city_id>  //int64, 城市ID
+    <id>0</id>  //int64, 地址ID
   </demo>
-  <msg>success</msg> //string, 返回消息
+  <msg>success</msg>  //string, 返回消息
 </response>
 ```
 
 ```xml
 //StatusCode: 200 
-<response> //object(common.Response), 通用返回结果
-  <code>0</code> //int, 返回状态码
-  <data> //object(handler.DemoXMLResponse2), XML测试返回对象2
-    <address>string</address> //string, 地址信息
-    <city_id>0</city_id> //int64, 城市ID
-    <id>0</id> //int64, 地址ID
+<response>  //object(common.Response), 通用返回结果
+  <code>0</code>  //int, 返回状态码
+  <data>  //object(handler.DemoXMLResponse2), XML测试返回对象2
+    <address>string</address>  //string, 地址信息
+    <city_id>0</city_id>  //int64, 城市ID
+    <id>0</id>  //int64, 地址ID
   </data>
-  <msg>success</msg> //string, 返回消息
+  <msg>success</msg>  //string, 返回消息
 </response>
 ```
 
 ```xml
 //StatusCode: 200 
-<response> //object(common.Response), 通用返回结果
-  <code>10010</code> //int, 返回状态码
-  <msg>sme error</msg> //string, 返回消息
+<response>  //object(common.Response), 通用返回结果
+  <code>10010</code>  //int, 返回状态码
+  <msg>sme error</msg>  //string, 返回消息
 </response>
 ```