
# Controller annotations

These annotations turn a class into a web controller and decide how its answers and errors look. The web server (`spring_boot_starter_web`) reads them; they live in this package so that other packages can see them without depending on the server.

## Why

A library that adds endpoints, or a tool that lists an application's API, needs the annotations but not a running server. Keeping them here keeps those dependencies light.

## Example

```dart
@RestController()
@RequestMapping('/api/books')
@CrossOrigin(origins: ['https://shop.neon.books']) // the shop's pages may call it
class BookController {
  BookController(this.books);

  final BookService books;

  // POST /api/books answers 201 Created instead of 200.
  @PostMapping()
  @ResponseStatus(HttpStatus.created)
  Future<Book> create(@RequestBody() Book book) => books.create(book);

  // A book that is already there becomes a 409 for every method above.
  @ExceptionHandler()
  ProblemDetail duplicate(DuplicateBookException e) =>
      ProblemDetail.forStatusAndDetail(HttpStatus.conflict, e.message);
}
```

## The annotations

| Annotation | On | Spring | Meaning |
|---|---|---|---|
| `@RestController([name])` | class | `@RestController` | A bean whose mapped methods answer requests; the return value is the response body. |
| `@RequestMapping('/api/books')` | class | the same | The path prefix of every method, and `produces`, `consumes`, `headers` for all of them. |
| `@ResponseStatus(HttpStatus.created, reason: ...)` | method, controller class | the same | The status of a normal answer. With `reason`, the result is ignored and the answer is an error with the reason as its detail. |
| `@ExceptionHandler([types])` | method | the same | Handles exceptions thrown by the controller's methods (by every controller's, in an advice). The exception parameter's type picks them, or `types`, matched by exact runtime type. |
| `@ControllerAdvice([name])`, `@RestControllerAdvice([name])` | class | the same | Exception handlers for every controller, tried in `@Order`. |
| `@CrossOrigin(origins:, originPatterns:, methods:, allowedHeaders:, exposedHeaders:, allowCredentials:, allowPrivateNetwork:, maxAge:)` | class, method | the same | Lets web pages of other origins call the controller (CORS). `maxAge` is in seconds. |

`@CrossOrigin()` with no arguments allows every origin, the method the handler is mapped to (`DELETE` for a `@DeleteMapping`, `GET` alone for a `@GetMapping`), every request header, no credentials, and a pre-flight cache of 30 minutes, as in Spring.

How the server applies them is described in the web starter: [@RestController](../spring-boot-starter-web/controllers/rest-controller.md), [@ExceptionHandler](../spring-boot-starter-web/errors/exception-handler.md), [@ControllerAdvice](../spring-boot-starter-web/errors/controller-advice.md), [CORS](../spring-boot-starter-web/cors.md).

## In Spring (Java)

```java
@RestController
@RequestMapping("/api/books")
@CrossOrigin(origins = "https://shop.neon.books")
class BookController { ... }
```

The same annotations. `@ExceptionHandler(types)` matches by exact runtime type: Dart cannot test at run time whether one `Type` is a subtype of another.

## See also

- [Mapping annotations](mapping-annotations.md)
- [HTTP types](http-types.md)
- [Controllers in the web starter](../spring-boot-starter-web/controllers/index.md)
