FAQ

Frequently asked questions about EasyApi.

How do I add a custom configuration?

Create a .easy.api.config file in your project root. See Local File Config for details.

How do I mark an API as deprecated?

Use the @Deprecated annotation on the method or class:

@Deprecated
@GetMapping("/old-api")
public Result oldApi() {
    // ...
}

Or use the ignore rule to exclude deprecated APIs:

ignore=groovy:it.hasAnn("java.lang.Deprecated")

How do I ignore specific fields?

Use the field.ignore rule:

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

# Ignore by annotation
field.ignore=groovy:it.hasAnn("com.fasterxml.jackson.annotation.JsonIgnore")

See Field Rules for more options.

How do I ignore specific APIs?

Use the ignore rule:

# Ignore by annotation
ignore=groovy:it.hasAnn("java.lang.Deprecated")

# Ignore by name pattern
ignore=#regex:^internal.*

How do I group APIs into folders?

Use the folder.name rule:

# Group by package
folder.name=groovy:it.packageName().split("\\.")[-1]

# Group by annotation value
folder.name=groovy:it.ann("org.springframework.web.bind.annotation.RequestMapping")?.value()

How do I handle multiple return types?

Use @return tags in your Java doc:

/**
 * Get user info
 * @return success {@link User} User info
 * @return unauthorized {@link Error} Not authenticated
 */
@GetMapping("/users/{id}")
public Object getUser(@PathVariable Long id) {
    // ...
}

How do I handle field type conversion?

Use json.rule.convert:

# Convert custom types
json.rule.convert[#regex:com.example.Wrapper<(.*?)>]=${1}
json.rule.convert[#regex:java.time.LocalDate]=java.lang.String

See JSON Rules for more options.

How do I add Spring Security permission info?

Use method.additional.header to add authorization headers:

method.additional.header=groovy:{"name":"Authorization","value":"Bearer ${token}","desc":"Auth token","required":true}

How do I use javax.validation with groups?

See javax.validation for detailed group-based validation configuration.