將go的結構定義轉化為markdown 表格(幫助快速生產文件)

eleztian發表於2022-10-29
Go

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

本作品採用《CC 協議》，轉載必須註明作者和本文連結

相關文章