Operation model

Generated code constructs these classes inline. You only need them to add operations by hand, for example for a route you register without a controller, or to inspect OpenApiSpec.paths.

Operation

A single HTTP operation.

class Operation {
  Operation({
    this.summary,
    this.description,
    this.operationId,
    this.deprecated = false,
    this.tags = const <String>[],
    this.parameters = const <Parameter>[],
    this.requestBody,
    this.responses = const <String, ResponseSpec>{},
    this.requiresAuth = false,
    this.permissions = const <String>[],
    this.anyPermission = const <String>[],
    this.roles = const <String>[],
  });

  Map<String, Object?> toMap({Iterable<String> securitySchemes = const <String>[]});
}

When to use: with OpenApiSpec.putOperation to document a route that is not generated from a controller (a plain Shelf handler, a mounted sub-app).

Parameter	Type	Default	Description
summary, description, operationId	String?	null	Emitted when set.
deprecated	bool	false	Emits deprecated: true.
tags	List<String>	[]	Operation tags.
parameters	List<Parameter>	[]	Path, query, header or cookie parameters.
requestBody	RequestBody?	null	Request body.
responses	Map<String, ResponseSpec>	{}	Status code (as a string) to response.
requiresAuth	bool	false	When true and the spec has security schemes, emits security with one alternative per scheme.
permissions	List<String>	[]	From @Permissions. Listed in security and x-gisila-guards.
anyPermission	List<String>	[]	From @AnyPermission. Listed only in x-gisila-guards (OpenAPI has no “any of” form).
roles	List<String>	[]	From @Roles. Listed in security and x-gisila-guards.

toMap is called by OpenApiSpec.toMap with the scheme names in effect. Each security entry carries [...roles, ...permissions] as its scope list.

Example

import 'package:gisila_doc/gisila_doc.dart';

spec.putOperation('/healthz', 'get', Operation(
  summary: 'Liveness probe',
  tags: ['Ops'],
  responses: {
    '200': ResponseSpec(
      description: 'OK',
      content: {
        'application/json': MediaType(schema: {
          'type': 'object',
          'properties': {'status': {'type': 'string'}},
        }),
      },
    ),
  },
));

Parameter

One operation parameter.

class Parameter {
  const Parameter({
    required this.name,
    required this.location,
    required this.schema,
    this.required = false,
    this.description,
    this.example,
  });
}

When to use: inside a hand-built Operation.

Parameter	Type	Default	Description
name	String	required	Parameter name.
location	String	required	Emitted as in: query, path, header or cookie.
schema	Map<String, Object?>	required	JSON schema.
required	bool	false	Must be true for path parameters.
description	String?	null	Description.
example	Object?	null	Emitted when set.

RequestBody

An operation’s request body.

class RequestBody {
  const RequestBody({
    required this.content,
    this.required = true,
    this.description,
  });
  final Map<String, MediaType> content;
}

When to use: inside a hand-built Operation. content maps media types (application/json, multipart/form-data, …) to MediaType.

ResponseSpec

One response entry.

class ResponseSpec {
  const ResponseSpec({required this.description, this.content});
  final String description;
  final Map<String, MediaType>? content;
}

When to use: inside Operation.responses. Leave content null (or empty) for responses without a body.

MediaType

Schema (and optional example) for one media type.

class MediaType {
  const MediaType({required this.schema, this.example});
  final Map<String, Object?> schema;
  final Object? example;
}

When to use: as the value in RequestBody.content and ResponseSpec.content. Use a $ref map ({r'$ref': '#/components/schemas/User'}) to point at a registered component.