documentOperations method Null safety

  1. @override
Map<String, APIOperation> documentOperations(
  1. APIDocumentContext context,
  2. String route,
  3. APIPath path
)
override

Tells this object to return all APIOperations it handles.

You implement this method to create or modify APIOperation objects that describe the HTTP operations that a controller handles. Each controller in the channel, starting with the entry point, have this method.

By default, a controller returns the operations created by its linked controllers.

Endpoint controllers should override this method to create a Map of APIOperation objects, where the key is a String representation of the status code the response is for. Example:

  @override
  Map<String, APIOperation> documentOperations(APIDocumentContext context, APIPath path) {
    if (path.containsPathParameters(['id'])) {
      return {
        "get": APIOperation("Get one thing", {
          "200": APIResponse(...)
        })
      };
    }

    return {
      "get": APIOperation("Get some things", {
        "200": APIResponse(...)
      })
    };
  }

Middleware controllers should override this method to call the superclass' implementation (which gathers the operation objects from an endpoint controller) and then modify those operations before returning them.

  @override
  Map<String, APIOperation> documentOperations(APIDocumentContext context, APIPath path) {
    final ops = super.documentOperation(context, path);

    // add x-api-key header parameter to each operation
    ops.values.forEach((op) {
      op.addParameter(new APIParameter.header("x-api-key, schema: new APISchemaObject.string()));
    });

    return ops;
  }

Implementation

@override
Map<String, APIOperation> documentOperations(
  APIDocumentContext context,
  String route,
  APIPath path,
) {
  return {
    "get": APIOperation(
      "getFile",
      {
        "200": APIResponse(
          "Successful file fetch.",
          content: {"*/*": APIMediaType(schema: APISchemaObject.file())},
        ),
        "404": APIResponse("No file exists at path.")
      },
      description: "Content-Type is determined by the suffix of the file.",
      summary: "Returns the contents of a file on the server's filesystem.",
    )
  };
}