将go的结构定义转化为markdown 表格(帮助快速生产文档)

Type2md - Golang Type To Markdown

github.com/eleztian/type2md

通过ast解析 将golang 的结构定义转化为markdown 表格。

支持将golang 的数据类型定义转化为markdown 表格

• 支持自定义 struct tag
• 支持注释解析
• 支持默认值定义
• 支持是否必填
• 支持外部mod 类型引用解析。
• 表格类型支持跳转

Usage

安装

$ go install github.com/eleztian/type2md

使用

$ type2md -h
Usage of type2md:
  -f string
        file path
  -t string
        file title
  -tag string
        struct tag name (default "json")
  -v    show version

Example

package test

import "github.com/eleztian/type2md/test/ext"

//go:generate type2md -f ../docs/doc_config.md github.com/eleztian/type2md/test Config

// Config doc.
type Config struct {
	Pre     ext.Hook
	Post    *ext.Hook
	Servers map[string]struct {
		Host string `json:"host,omitempty"`
		Port int    `json:"port" enums:"22,65522" require:"false"`
	} `json:"servers"` // server list
	InlineStruct `json:",inline"` // inline struct
	Slice        []string         // sss
	MapData      map[string]map[int]*OtherStruct
	ArrayData    [][2]string   `json:"array_data"`
	C            []interface{} // slice interface{}
}

// InlineStruct inline struct.
type InlineStruct struct {
	A string `json:"a"` // inline struct field a
}

// OtherStruct other struct
// this is use for test.
type OtherStruct struct {
	A string                 `json:"a" require:"true" default:"default value"`
	B [][2]ext.Mode          `json:"b"` // array string
	C map[string]interface{} `json:"c"` // map[string]interface{}
	D *OtherStruct           `json:"d"` // nested struct
}

执行下列命令

$ go generate  ./...          
2022/10/28 23:56:16 Current Module: github.com/eleztian/type2md
2022/10/28 23:56:16 start generate github.com/eleztian/type2md/test.Config
2022/10/28 23:56:16 start to save to ../docs/doc_config.md

得到下面的文档：

---

Config Doc

Config doc.

Key	Type	Require	Default	Describe
Pre	Hook	true
Post	Hook	true
servers.{string}.host	string	false
servers.{string}.port	int	false		- 22 - 65522
a	string	true		inline struct field a.
Slice.[]	string	true		sss.
MapData.{string}.{int}.	OtherStruct	true
array_data.[] .[2]	string	true
C.[]	any	true		slice interface{}.

ext.Hook

Hook hook config.

Key	Type	Require	Default	Describe
name	string	false	example	hook name.
commands.[]	string	true		command list.
envs.{string}	string	true		env key map.
mode	Mode	true	1	run mode.

OtherStruct

OtherStruct other struct
this is use for test.

Key	Type	Require	Default	Describe
a	string	true	default value
b.[] .[2]	Mode	true		array string.
c.{string}	any	true		map[string] interface{}.
d	OtherStruct	true		nested struct.

ext.Mode

Type: int
Mode mode define.

Enum Value	Describe
1	mode q.
2	mode a.

---

github.com/eleztian/type2md/test.Config
GENERATED BY THE COMMAND type2md