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,
) {
  final operations = super.documentOperations(context, route, path);

  operations.forEach((_, op) {
    op.addResponse(400, context.responses["MalformedAuthorizationHeader"]);
    op.addResponse(401, context.responses["InsufficientAccess"]);
    op.addResponse(403, context.responses["InsufficientScope"]);

    final requirements = validator!
        .documentRequirementsForAuthorizer(context, this, scopes: scopes);
    for (final req in requirements) {
      op.addSecurityRequirement(req);
    }
  });

  return operations;
}