tip

This feature is an experimental feature, available from version v2.4.

Introduction

This command is used to analyze the source code in the specified code directory and generate enum values and Go code files according to specifications, mainly to improve the maintenance of enum values in OpenAPIv3 documents.

Addressed Pain Points

Pain Points Description

• The issue of not displaying the optional items of enum values in the API documentation.
• The difficulty in maintaining enum values in the API documentation, and the issue of code and documentation being maintained separately. This reduces the collaboration efficiency with the caller, especially between frontend and backend.

For example, in the following API definition, tasks have multiple states which are enum values. It's costly for the backend to maintain and easy to miss states maintenance, causing incomplete state enum values.

Pain Points Resolution

The tool parses source code and generates enum values into the startup package Go file, automatically loading enum values when the service runs, reducing manual maintenance costs and avoiding omitted enum value maintenance.

For example, in the following API definition, using the tool to maintain enum values improves development efficiency.

Command Usage

$ gf gen enums -h
USAGE
    gf gen enums [OPTION]

OPTION
    -s, --src        source folder path to be parsed
    -p, --path       output go file path storing enums content
    -x, --prefixes   only exports packages that starts with specified prefixes
    -h, --help       more information about this command

EXAMPLE
    gf gen enums
    gf gen enums -p internal/boot/boot_enums.go
    gf gen enums -p internal/boot/boot_enums.go -s .
    gf gen enums -x github.com/gogf

Parameter Description:

Name	Required	Default	Description
src	No	.	Specify the source code directory path for analysis, default is the current project root directory
path	No	internal/boot/boot_enums.go	Specify the path for the generated enum registration Go code file
prefixes	No	-	Only generate enum values for package names with specified prefixes, supports multiple prefix configurations

info

This command uses AST parsing to recursively analyze enums definitions for all dependency packages. If the business project dependencies are complex, the generated enums may be many, but most of the time we only care about the enums definitions of our own project or specific dependency packages, hence the prefixes parameter can be used to control the generation of enums for only specific package name prefixes.

Example of the tool configuration item in yaml format:

hack/config.yaml

gfcli:
  gen:
    enums:
      src:  "api"
      path: "internal/boot/boot_enums.go"
      prefixes: 
      - github.com/gogf
      - myexample/project

Usage of the Generated File

Execute the gf gen enums command to generate the enum analysis file internal/boot/boot_enums.go. After generating the file, it needs to be anonymously imported in the project's entry file:

import (
    _ "project_module_name/internal/boot"
)

Further Reading

How to Standardize Enum Values

Please refer to the section: Golang Enums

How to Validate Enum Values

If enum values are standardized and files are generated by command for enum value maintenance, then in parameter validation, the enums rule can be used to validate enum value fields. For specific rule introduction, please refer to the section: Data Validation - Rules