Generate API Docs using external tool

[a0v0]

Problem

When generating api documentaion using the command goctl api go -api test.api. Broken json file is produced. Moreover wrong query, path param are mapped in the generated swagger file.

problem 1

problem 2

a sample request struct in test.api file

GetPublicUserAccountRequest {
		UserId   string `json:"user_id,optional" validate:"uuid"` 
		Username string `josn:"username,optional"`                
	}

here is the generated swagger file. see the required field

...
"GetPublicUserAccountRequest": {
      "type": "object",
      "properties": {
        "user_id": {
          "type": "string",
          "description": " The user ID of the user."
        },
        "Username": {
          "type": "string",
          "description": " The username assosciated with the account. Min 5 characters, max 50 characters. Only lowercase alphanumeric characters allowed."
        }
      },
      "title": "GetPublicUserAccountRequest",
      "required": [
        "uuid"
      ]
    },
...

Solution

Use already mature tool https://github.com/swaggo/swag

How to integrate without breaking changes?

Step 1: Replace the older comment format with the new one

older:

service backbone {
@doc(
		summary: Update User Account
		description: Update the account of currently logged in user. An empty 200 response indicates account update was successful.
	)
	@handler updateUserAccount
	post /account/update(UpdateUserAccountRequest) returns (UpdateUserAccountResponse)
}

new format:

	// UpdateMedia godoc
	// @Summary      Update Media File Metadata
	// @Description  Update metadata assosiated the media file.
	// @Description  Returns empty 200 ok response if successful.
	// @Accept       json
	// @Produce      json
	// @Param        types.UpdateMediaRequest  body      types.UpdateMediaRequest  true  "Update Media Request"
	// @Success      200      {object}  types.UpdateMediaResponse
	// @Router       /media/update [post]
	@handler updateUserAccount
	post /account/update(UpdateUserAccountRequest) returns (UpdateUserAccountResponse)
	

Basically retain any comment above the @handler (including multiline) and put these comments handler function in generated handler files. See below

// UpdateMedia godoc
// @Summary      Update Media File Metadata
// @Description  Update metadata assosiated the media file.
// @Description  Returns empty 200 ok response if successful.
// @Accept       json
// @Produce      json
// @Param        types.UpdateMediaRequest  body      types.UpdateMediaRequest  true  "Update Media Request"
// @Success      200      {object}  types.UpdateMediaResponse
// @Router       /media/update [post]
func UpdateUserAccountHandler(svcCtx *svc.ServiceContext) http.HandlerFunc {
	return func(w http.ResponseWriter, r *http.Request) {
		var req types.UpdateUserAccountRequest

		// go-zero validation
		if err := httpx.Parse(r, &req); err != nil {
			result.ParamErrorResult(r, w, err)
			return
		}
		l := userAccount.NewUpdateUserAccountLogic(r.Context(), svcCtx)
		resp, err := l.UpdateUserAccount(&req)
		result.HttpResult(r, w, resp, err)
	}
}

Does main.go file needs to be changed?

Yes. First install https://github.com/swaggo/swag and run swag init to generate a docs folder. Now int the main.go file add this import line _ "<packagename>/docs".

To add title, email, other meta add these comments above the main() function call or reference the swaggo/swag package for usage

package main

// TODO write tests

import (
	"fmt"
	"log"

	_ "example.com/docs"

	"github.com/zeromicro/go-zero/rest"
)


// @title           API
// @version         1.0
// @description     This is a sample server celler server.
// @termsOfService  http://example.com/terms/

// @contact.name   API Support
// @contact.url    http://www.example.com/support
// @contact.email  support@example.com

// @host      localhost:8080
// @BasePath  /
func main() {
...

@kevwan hope to see this in next release.

Maybe #2326 needs to be fixed first.

[WqyJh]

I write an api generation plugin to solve this problem, see https://github.com/WqyJh/goctl-gogen.