@PathAlias

@PathAlias was added in version 2.4 and requires miredot-annotations version 1.6+.

The @PathAlias annotation allows you to override the URL of your REST interface in the documentation generated by Miredot.

Just like the @Path annotation, @PathAlias is relative to the context of the REST interface and can be specified both at the class or method level of a resource. It differs from @Path in that it supports multiple aliases, and therefore requires a String[] instead of a String as its parameter. When using multiple aliases, the generated documentation will duplicate the documentation of the REST endpoint for each alias.

Using @PathAlias is useful when you use a regular expression in @Path, but wish to document the REST interface using concrete values instead of the regular expression, as shown in the following code example:

@Path("/path/to/{a: group|subgroup}")
@PathAlias({"/path/to/group", "/path/to/subgroup"})
public void myMethod() { ... }

This results in:

└── path
    └── to
        ├── group
        └── subgroup

Defining @PathAlias on both the class and the method level will work multiplicatively, so that every alias specified at the method level will be listed for every alias specified at the class level.

The annotation also supports resource locators and sub-resources. Like @Path, you can specify @PathAlias annotation on the resource class, the locator method returning a sub-resource, or methods of the sub-resource itself.

Examples

@Path("/path/to/{a: group|subgroup}")
public void myMethod() { ... }

└── path
    └── to
        └── {a: group|subgroup}

@Path("/path/to/{a: group|subgroup}")
@PathAlias({"/path/to/group"})
public void myMethod() { ... }

└── path
    └── to
        └── group

@Path("/path/to/{a: group|subgroup}")
@PathAlias({"/path/to/group",
            "/path/to/subgroup"})
public void myMethod() { ... }

└── path
    └── to
        ├── group
        └── subgroup

@Path("/{a: some-url|some-path}")
@PathAlias({"/some-url", "/some-path"})
public class EndPoint {

    @Path("/path/to/{a: group|subgroup}")
    @PathAlias({"/path/to/group",
                "/path/to/subgroup"})
    public void myMethod() { ... }

}

├── some-url
│   └── path
│       └── to
│           ├── group
│           └── subgroup
└── some-path
    └── path
        └── to
            ├── group
            └── subgroup