apidocgen

apidocgen

apidocgen is a tool for Go to generate apis markdown docs and mocks.

Install

go install github.com/alovn/apidocgen@latest

Cli

$ apidocgen --help
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=

Usage:
  apidocgen [flags]
  apidocgen [command]

Available Commands:
  help        Help about any command
  mock        
  version     print version

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 templates include markdown and apidocs, default is markdown.

The template apidocs is the template for generate website apidocs.

You can also use the custom template:

apidocgen \
    --dir=svc-user,common \
    --template=/Users/xxx/workspace/apidocs/custom-template-direcoty \
    --output=./docs

How to use

apidocgen supported any web frameworks. here are an example using bytego.

1. Add API annotations in main.go code:

   //@title UserService
   //@service svc-user
   //@version 1.0.1
   //@desc the api about users
   //@baseurl /user
   func main() {
       r := bytego.New()
       c := controller.NewController()
       //@group account
       //@title Account
       //@desc account register and login
       account := r.Group("/account")
       {
           account.POST("/register", c.Register)
           account.POST("/login", c.Login)
       }
       _ = r.Run(":8000")
   }
   

2. Add API annotations in httpHandler.

   //@title AccountLogin
   //@api POST /account/login
   //@group account
   //@accept json
   //@format json
   //@request LoginRequest
   //@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
       res := common.NewResponse(0, "success", &LoginResponse{
           WelcomeMsg: "welcome",
       })
       c.JSON(http.StatusOK, res)
   }
   

3. Execute apidocgen.

   apidocgen
   

   The markdown files will be generated in ./docs.

Examples

Some examples and generated markdown docs are here: apidocgen/examples.

An online generated api docs site: https://apidocgen.netlify.app/

Comments(annotations)

Response

1. response user defined struct.

   type User struct {
       ID int `json:"id"`
       Name string `json:"name"`
   }
   
   //@response 200 User "description"
   

2. response struct with array.

   //@response 200 []User
   

3. a composition common response.

   type Response struct {
       Code int `json:"code"`
       Msg string `json:"msg"`
       Data interface{} `json:"data"`
   }
   
   //@response 200 Response{code=10001,msg="some error"} "some error description"
   //@response 200 Response{code=0,data=User} "success description"
   //@response 200 Response{code=0,data=[]User} "success description"
   

   if import package of common.Response:

   import (
       "common"
   )
   
   //@response 200 common.Response{code=0,data=User} "success description"
   

4. example value of struct

   type User struct {
       ID int `json:"id" example:"100010"`
       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.

   //@response 200 Response{code=0,data=[]User} "success description" //mock
   

   generate apis mocks files, default generated in the directory ./docs/mocks.

   apidocgen --dir=common,svc-user --gen-mocks
   

2. serve the mock server from source code.

   apidocgen --dir=common,svc-user --mock --mock-listen=:8001
   

3. serve the mock server from generated mock files.

   apidocgen mock --data=./mocks --listen=:8001
   

   $ curl -X POST -d "" localhost:8001/user/account/login   
   {
     "code": 0,
     "data": {
       "welcome_msg": "string"
     },
     "msg": "success"
   }