Local File Config

You can create local configuration files to customize EasyApi behavior for your project. EasyApi supports two file models: the folder-based rule model (recommended) and the legacy single-file model (kept for backward compatibility).

Folder-Based Rule Model (Recommended)

EasyApi loads rule files from .easyapi/ folders. Files can use any name with a .rules or .properties extension.

Project-scoped rules

Create files in <project>/.easyapi/:

<project>/
├── .easyapi/
│   ├── security.rules       # security-related rules (headers, auth)
│   ├── naming.rules          # field/param naming conventions
│   └── postman.rules         # Postman export tweaks
└── src/

These rules apply only to the current project.

Global rules

Create files in ~/.easyapi/:

~/.easyapi/
├── common.rules              # rules shared across all projects
└── team-conventions.rules    # team-wide conventions

These rules apply to every project on your machine.

Managing rule files in the IDE

Open Settings → EasyApi → Rules to manage rule files without leaving the IDE. The tab has three sub-tabs:

• Project — create, edit, enable, and disable rule files in <project>/.easyapi/
• Global — manage rule files in ~/.easyapi/
• Remote — remote config URLs (see Remote Config)

Individual rule files can be toggled on or off from this panel without deleting them.

Reload on change

EasyApi watches the .easyapi/ folders and reloads rule files automatically when they change. You can also trigger a reload by saving a file from the Rules tab or by running any export/call action.

Rule file format

Each line is one rule: <key>[<filter>]=<value>. See Config Rules for the full syntax, filter prefixes, and the rule-key catalog.

# security.rules
# Add an auth header to every endpoint in the admin package
method.additional.header[groovy: it.containingClass().name().startsWith("com.example.admin.")]={"name":"Authorization","value":"Bearer ${token}","desc":"auth token","required":true}

# naming.rules
# Rename createTime -> created_at in DTOs
field.name={"createTime":"created_at"}

# postman.rules
# Set the Postman host for this project
postman.host=https://api.example.com

Legacy Single-File Model

The older single-file model is still supported for backward compatibility. Create a file named .easy.api.config in your project root directory. EasyApi will automatically load this file.

You can also use YAML format with the following file names:

• .easy.api.config — Properties format (default)
• .easy.api.yml — YAML format
• .easy.api.yaml — YAML format

If both a .easyapi/ folder and a legacy .easy.api.config file exist, the folder-based rules take priority. See Rule Priority for the full merge order.

Config File Location

EasyApi searches for configuration files in the following order:

1. .easyapi/*.rules files in the project directory (folder model)
2. .easy.api.config / .easy.api.yml / .easy.api.yaml in the module directory (legacy)
3. .easy.api.config / .easy.api.yml / .easy.api.yaml in the project root directory (legacy)
4. Global rules in ~/.easyapi/*.rules (folder model)
5. IDE settings (Preferences > Other Settings > EasyApi)
6. Built-in recommended configuration

Config File Format

The configuration file uses a simple key-value format:

# This is a comment

# Import additional properties
properties.additional=${module_path}/src/main/resources/application.properties

# Set API name
api.name=#regex:^(.+)Controller$=$1

# Set class prefix path
class.prefix.path=${server.servlet.context-path}

# Ignore specific fields
field.ignore=groovy:it.name() == "password"

# Set field default value
field.default.value=groovy:it.hasAnn("javax.validation.constraints.NotNull") ? "required" : null

YAML Format

When using .easy.api.yml or .easy.api.yaml, the configuration uses YAML format:

# Set API name
api:
  name: "#regex:^(.+)Controller$=$1"

# Set class prefix path
class:
  prefix:
    path: "${server.servlet.context-path}"

# Ignore specific fields
field:
  ignore: "groovy:it.name() == 'password'"

# Set field default value
field:
  default:
    value: "groovy:it.hasAnn('javax.validation.constraints.NotNull') ? 'required' : null"

# Type conversions
json:
  rule:
    convert:
      "#regex:org.springframework.http.ResponseEntity<(.*?)>": "${1}"

Property Resolution

You can reference Spring properties in your configuration:

# Resolve spring properties
###set ignoreUnresolved = true
class.prefix.path=${server.servlet.context-path}
###set ignoreUnresolved = false

The ###set ignoreUnresolved = true directive tells EasyApi to not throw an error if the property cannot be resolved.

Including Other Config Files

Use the ###include directive (since v3.1.6) to split your configuration across multiple files and pull them into the current file inline. The directive must be on its own line:

# Include a local file (relative to this file, or absolute, or ~/...)
###include ./security.rules
###include ~/team-conventions.rules

# Include a remote config over HTTP/HTTPS
###include https://raw.githubusercontent.com/your-org/configs/main/easyapi.config

The included file's contents are parsed with the same directive state as the calling file — so ###set ignoreUnresolved = true (and the other ###set options) carry into the included content. Relative paths in an included file resolve against the included file's own directory (or, for a remote include, against the same host).

###include is the preferred syntax; the legacy properties.additional key (below) is kept for backward compatibility and behaves identically — both forms resolve local paths and remote URLs the same way.

###set ignoreNotFoundFile

By default, an include that cannot be resolved throws an error. Wrap unknown-may-not-exist includes with the ignoreNotFoundFile directive to silence missing-file errors:

###set ignoreNotFoundFile = true
###include ${module_path}/src/main/resources/optional-rules.properties
###set ignoreNotFoundFile = false

Adding Config Sources

You can add additional configuration sources (legacy form, equivalent to ###include):

# Add local property files
properties.additional=${module_path}/src/main/resources/application.properties
properties.additional=${module_path}/src/main/resources/application.yml

# Add remote config files
properties.additional=https://raw.githubusercontent.com/your-org/configs/main/easyapi.config