update(conduit): refactoring open_api to openapi

packages/openapi/lib/src/util/list_helper.dart

@@ -23,6 +23,8 @@
 List<String>? removeNullsFromList(List<String?>? list) {
   if (list == null) return null;
 
-  // remove nulls and convert to List<String>
+  // Remove null entries from the list using the 'nonNulls' property
+  // which returns an Iterable containing only the non-null elements
+  // Convert the resulting Iterable to a List<String> using toList()
   return list.nonNulls.toList();
 }

packages/openapi/lib/src/util/map_helper.dart

@@ -26,10 +26,14 @@ Map<K, V> removeNullsFromMap<K, V>(Map<K, V?>? map) {
 
   final fixed = <K, V>{};
 
-  // remove nulls
+  // Iterate through all keys in the input map
   for (final key in map.keys) {
+    // Get the value associated with the current key
     final value = map[key];
+    // Check if the value is not null
     if (value != null) {
+      // If the value is not null, add it to the 'fixed' map
+      // This effectively removes all null values from the original map
       fixed[key] = value;
     }
   }

packages/openapi/lib/src/v2/operation.dart

@@ -13,9 +13,39 @@ import 'package:protevus_openapi/object.dart';
 import 'package:protevus_openapi/v2.dart';
 
 /// Represents a HTTP operation (a path/method pair) in the OpenAPI specification.
+///
+/// This class extends [APIObject] and provides properties and methods to handle
+/// various aspects of an API operation, including:
+/// - Tags associated with the operation
+/// - Summary and description of the operation
+/// - Consumes and produces content types
+/// - Deprecated status
+/// - Parameters and responses
+/// - Security requirements
+///
+/// The class implements [Codable] interface through [APIObject], allowing
+/// for easy encoding and decoding of the operation data.
 class APIOperation extends APIObject {
+  /// Creates a new instance of [APIOperation].
+  ///
+  /// This constructor initializes a new [APIOperation] object without any
+  /// predefined values. Properties can be set after initialization.
   APIOperation();
 
+  /// Defines the type casting rules for specific properties of the [APIOperation] class.
+  ///
+  /// This getter method returns a [Map] where the keys are property names and the values
+  /// are [cast.Cast] objects that define how these properties should be type-casted.
+  ///
+  /// The map includes the following castings:
+  /// - "tags": A list of strings
+  /// - "consumes": A list of strings
+  /// - "produces": A list of strings
+  /// - "schemes": A list of strings
+  /// - "security": A list of maps, where each map has string keys and list of string values
+  ///
+  /// This casting information is used to ensure type safety when decoding JSON data
+  /// into [APIOperation] objects.
   @override
   Map<String, cast.Cast> get castMap => {
         "tags": const cast.List(cast.string),
@@ -26,19 +56,118 @@ class APIOperation extends APIObject {
             const cast.List(cast.Map(cast.string, cast.List(cast.string))),
       };
 
+  /// A brief summary of the operation.
+  ///
+  /// This property provides a short description of what the operation does.
+  /// It's typically used to give a quick overview of the operation's purpose
+  /// in API documentation or user interfaces.
   String? summary = "";
+
+  /// A detailed description of the operation.
+  ///
+  /// This property provides a more comprehensive explanation of what the operation does,
+  /// how it works, and any important details that users or developers should know.
+  /// It can include information about request/response formats, authentication requirements,
+  /// or any other relevant details about the operation's behavior.
   String? description = "";
+
+  /// The unique identifier for this operation.
+  ///
+  /// This property represents the operationId as defined in the OpenAPI specification.
+  /// It's used to uniquely identify an operation within an API. The operationId is often
+  /// used as a reference point in documentation, client libraries, and other tooling.
   String? id;
+
+  /// Indicates whether this operation is deprecated.
+  ///
+  /// If set to `true`, it means that the operation is still functional but its
+  /// use is discouraged. Clients should migrate away from using this operation.
+  /// If `false` or `null`, the operation is considered active and recommended for use.
   bool? deprecated;
 
+  /// A list of tags associated with this operation.
+  ///
+  /// Tags are used to group operations in the OpenAPI specification. They can be used
+  /// for logical grouping of operations by resources or any other qualifier.
+  /// This property is nullable and can be an empty list if no tags are specified.
   List<String?>? tags = [];
+
+  /// A list of transfer protocols supported by this operation.
+  ///
+  /// This property specifies the schemes (such as 'http', 'https', 'ws', 'wss')
+  /// that the operation supports. It's typically used to indicate which
+  /// protocols can be used to access the API endpoint.
+  /// The list can be empty if no specific schemes are defined.
   List<String?>? schemes = [];
+
+  /// A list of MIME types the operation can consume.
+  ///
+  /// This property specifies the MIME types of the request payload that the operation
+  /// can process. It indicates the content types that the client can send in the request body.
+  /// Common values include 'application/json', 'application/xml', 'multipart/form-data', etc.
+  /// The list can be empty if the operation doesn't consume any specific MIME types.
   List<String?>? consumes = [];
+
+  /// A list of MIME types the operation can produce.
+  ///
+  /// This property specifies the MIME types of the response payload that the operation
+  /// can generate. It indicates the content types that the server will send in the response body.
+  /// Common values include 'application/json', 'application/xml', 'text/plain', etc.
+  /// The list can be empty if the operation doesn't produce any specific MIME types.
   List<String?>? produces = [];
+
+  /// A list of parameters for this operation.
+  ///
+  /// This property contains a list of [APIParameter] objects that define the
+  /// parameters accepted by the operation. These parameters can include path
+  /// parameters, query parameters, header parameters, and body parameters.
+  /// Each parameter specifies details such as name, location (in), type, and
+  /// whether it's required.
+  ///
+  /// The list can be empty if the operation doesn't require any parameters.
+  /// It's nullable to allow for cases where parameters are not specified.
   List<APIParameter?>? parameters = [];
+
+  /// A list of security requirements for this operation.
+  ///
+  /// This property defines the security schemes that apply to this operation.
+  /// Each item in the list is a map where:
+  /// - The key is the name of a security scheme defined in the global 'securityDefinitions'.
+  /// - The value is a list of scopes required for this operation (can be an empty list if no scopes are required).
+  ///
+  /// Multiple items in the list indicate that multiple security schemes can be used (OR relationship).
+  /// An empty list means that no security is required for this operation.
+  /// If this property is null, it inherits the global security requirements.
   List<Map<String, List<String>>?>? security = [];
+
+  /// A map of possible responses from this operation.
+  ///
+  /// The keys of this map are HTTP status codes (as strings), and the values
+  /// are [APIResponse] objects describing the response for that status code.
+  ///
+  /// For example, '200' might map to a successful response, '400' to a bad request
+  /// response, and so on. The map can include a 'default' key to describe the
+  /// response for any undocumented status codes.
+  ///
+  /// This property is nullable, allowing for operations that don't specify
+  /// their responses explicitly.
   Map<String, APIResponse?>? responses = {};
 
+  /// Decodes the [APIOperation] object from a [KeyedArchive].
+  ///
+  /// This method is responsible for populating the properties of the [APIOperation]
+  /// instance from the provided [KeyedArchive] object. It decodes various fields
+  /// such as tags, summary, description, operationId, consumes, produces, deprecated
+  /// status, parameters, responses, schemes, and security requirements.
+  ///
+  /// The method first calls the superclass's decode method to handle any base
+  /// properties, then proceeds to decode specific [APIOperation] properties.
+  ///
+  /// For complex properties like parameters and responses, it uses specialized
+  /// decoding methods that create new instances of [APIParameter] and [APIResponse]
+  /// respectively.
+  ///
+  /// @param object The [KeyedArchive] containing the encoded data to be decoded.
   @override
   void decode(KeyedArchive object) {
     super.decode(object);
@@ -56,6 +185,20 @@ class APIOperation extends APIObject {
     security = object.decode("security");
   }
 
+  /// Encodes the [APIOperation] object into a [KeyedArchive].
+  ///
+  /// This method is responsible for encoding the properties of the [APIOperation]
+  /// instance into the provided [KeyedArchive] object. It encodes various fields
+  /// such as tags, summary, description, operationId, consumes, produces, deprecated
+  /// status, parameters, responses, and security requirements.
+  ///
+  /// The method first calls the superclass's encode method to handle any base
+  /// properties, then proceeds to encode specific [APIOperation] properties.
+  ///
+  /// For complex properties like parameters and responses, it uses specialized
+  /// encoding methods that handle lists of objects and object maps respectively.
+  ///
+  /// @param object The [KeyedArchive] where the encoded data will be stored.
   @override
   void encode(KeyedArchive object) {
     super.encode(object);

packages/openapi/lib/src/v2/parameter.dart

@@ -10,10 +10,29 @@
 import 'package:protevus_typeforge/codable.dart';
 import 'package:protevus_openapi/v2.dart';
 
-/// Represents a parameter location in the OpenAPI specification.
+/// Enum representing the possible locations of a parameter in an API request.
+///
+/// The possible values are:
+/// - [query]: Parameter is passed as a query parameter in the URL
+/// - [header]: Parameter is included in the request headers
+/// - [path]: Parameter is part of the URL path
+/// - [formData]: Parameter is sent as form data in the request body
+/// - [body]: Parameter is sent in the request body (typically as JSON)
 enum APIParameterLocation { query, header, path, formData, body }
 
+/// A utility class for encoding and decoding [APIParameterLocation] enum values.
 class APIParameterLocationCodec {
+  /// Decodes a string representation of an API parameter location into an [APIParameterLocation] enum value.
+  ///
+  /// This method takes a [String] parameter [location] and returns the corresponding
+  /// [APIParameterLocation] enum value. If the input string doesn't match any known
+  /// location, the method returns null.
+  ///
+  /// Parameters:
+  ///   [location] - A string representing the API parameter location.
+  ///
+  /// Returns:
+  ///   The corresponding [APIParameterLocation] enum value, or null if no match is found.
   static APIParameterLocation? decode(String? location) {
     switch (location) {
       case "query":
@@ -31,6 +50,17 @@ class APIParameterLocationCodec {
     }
   }
 
+  /// Encodes an [APIParameterLocation] enum value into its string representation.
+  ///
+  /// This method takes an [APIParameterLocation] enum value as input and returns
+  /// the corresponding string representation. If the input is null or doesn't
+  /// match any known location, the method returns null.
+  ///
+  /// Parameters:
+  ///   [location] - An [APIParameterLocation] enum value to be encoded.
+  ///
+  /// Returns:
+  ///   A [String] representing the API parameter location, or null if the input is null or invalid.
   static String? encode(APIParameterLocation? location) {
     switch (location) {
       case APIParameterLocation.query:
@@ -50,21 +80,104 @@ class APIParameterLocationCodec {
 }
 
 /// Represents a parameter in the OpenAPI specification.
+///
+/// This class extends [APIProperty] and provides additional functionality
+/// specific to API parameters. It includes properties such as name, description,
+/// required status, and location of the parameter.
+///
+/// The class supports two main parameter types:
+/// 1. Body parameters: When [location] is [APIParameterLocation.body], it uses
+///    [schema] to define the parameter structure.
+/// 2. Non-body parameters: For all other locations, it uses properties inherited
+///    from [APIProperty] and adds [allowEmptyValue] and [items] for array types.
+///
+/// The class implements [Codable] through its superclass, providing [decode] and
+/// [encode] methods for serialization and deserialization.
 class APIParameter extends APIProperty {
+  /// Default constructor for [APIParameter].
+  ///
+  /// Creates a new instance of [APIParameter] with default values.
+  /// All properties are initialized to their default values as defined in the class.
   APIParameter();
 
+  /// The name of the API parameter.
+  ///
+  /// This property represents the name of the parameter as defined in the API specification.
+  /// It can be null if the name is not specified or not applicable.
   String? name;
+
+  /// A description of the API parameter.
+  ///
+  /// This property provides additional information about the parameter,
+  /// explaining its purpose, expected format, or any other relevant details.
+  /// It can be null if no description is provided.
   String? description;
+
+  /// Indicates whether the parameter is required.
+  ///
+  /// This boolean property determines if the API parameter is mandatory (true) or optional (false).
+  /// By default, it is set to false, meaning the parameter is optional unless specified otherwise.
   bool isRequired = false;
+
+  /// The location of the API parameter.
+  ///
+  /// This property specifies where the parameter should be placed in the API request.
+  /// It can be one of the following values from the [APIParameterLocation] enum:
+  /// - [APIParameterLocation.query]: Parameter is included in the URL query string
+  /// - [APIParameterLocation.header]: Parameter is included in the request headers
+  /// - [APIParameterLocation.path]: Parameter is part of the URL path
+  /// - [APIParameterLocation.formData]: Parameter is sent as form data in the request body
+  /// - [APIParameterLocation.body]: Parameter is sent in the request body (typically as JSON)
+  ///
+  /// The location can be null if it's not specified or not applicable.
   APIParameterLocation? location;
 
-  // Valid if location is body.
+  /// The schema object for the API parameter.
+  ///
+  /// This property is used when the [location] is [APIParameterLocation.body].
+  /// It defines the structure and validation rules for the parameter in the request body.
+  /// The schema is represented as an [APISchemaObject], which can describe complex
+  /// data structures including nested objects and arrays.
+  ///
+  /// This property is null for parameters that are not in the body location.
   APISchemaObject? schema;
 
-  // Valid if location is not body.
+  /// Indicates whether an empty value is allowed for this parameter.
+  ///
+  /// This property is only applicable for non-body parameters (i.e., when [location] is not [APIParameterLocation.body]).
+  /// When set to true, it allows the parameter to be sent with an empty value.
+  /// By default, it is set to false, meaning empty values are not allowed unless explicitly specified.
   bool allowEmptyValue = false;
+
+  /// Represents the items of an array-type parameter.
+  ///
+  /// This property is only used when [type] is [APIType.array]. It defines the
+  /// schema for the items in the array. The [APIProperty] object describes the
+  /// structure and validation rules for each item in the array.
+  ///
+  /// This property is null for non-array parameters or when not specified.
   APIProperty? items;
 
+  /// Decodes the parameter from a [KeyedArchive] object.
+  ///
+  /// This method populates the properties of the [APIParameter] instance
+  /// by decoding values from the provided [KeyedArchive] object. It handles
+  /// both body and non-body parameters differently:
+  ///
+  /// For all parameters:
+  /// - Decodes 'name', 'description', and 'in' (location) properties.
+  /// - Sets 'isRequired' based on the location or the 'required' field.
+  ///
+  /// For body parameters ([APIParameterLocation.body]):
+  /// - Decodes the 'schema' object.
+  ///
+  /// For non-body parameters:
+  /// - Calls the superclass decode method to handle common properties.
+  /// - Decodes 'allowEmptyValue'.
+  /// - For array types, decodes the 'items' property.
+  ///
+  /// Parameters:
+  ///   [object] - The [KeyedArchive] containing the encoded parameter data.
   @override
   void decode(KeyedArchive object) {
     name = object.decode("name");
@@ -87,6 +200,25 @@ class APIParameter extends APIProperty {
     }
   }
 
+  /// Encodes the parameter into a [KeyedArchive] object.
+  ///
+  /// This method serializes the properties of the [APIParameter] instance
+  /// into the provided [KeyedArchive] object. It handles both body and
+  /// non-body parameters differently:
+  ///
+  /// For all parameters:
+  /// - Encodes 'name', 'description', 'in' (location), and 'required' properties.
+  ///
+  /// For body parameters ([APIParameterLocation.body]):
+  /// - Encodes the 'schema' object.
+  ///
+  /// For non-body parameters:
+  /// - Calls the superclass encode method to handle common properties.
+  /// - Encodes 'allowEmptyValue' if it's true.
+  /// - For array types, encodes the 'items' property.
+  ///
+  /// Parameters:
+  ///   [object] - The [KeyedArchive] to store the encoded parameter data.
   @override
   void encode(KeyedArchive object) {
     object.encode("name", name);

packages/openapi/lib/src/v2/path.dart

@@ -11,13 +11,61 @@ import 'package:protevus_typeforge/codable.dart';
 import 'package:protevus_openapi/object.dart';
 import 'package:protevus_openapi/v2.dart';
 
-/// Represents a path (also known as a route) in the OpenAPI specification.
+/// Represents an API path in the OpenAPI specification.
+///
+/// This class extends [APIObject] and provides functionality to decode and encode
+/// API path information, including parameters and operations.
+///
+/// Properties:
+/// - [parameters]: A list of [APIParameter] objects associated with this path.
+/// - [operations]: A map of operation names to [APIOperation] objects for this path.
+///
+/// The [decode] method populates the object from a [KeyedArchive], handling parameters
+/// and operations separately. The [encode] method serializes the object back into
+/// a [KeyedArchive].
+///
+/// Note: The handling of '$ref' keys is currently a todo item.
 class APIPath extends APIObject {
+  /// Creates a new instance of [APIPath].
+  ///
+  /// This constructor initializes an empty [APIPath] object.
+  /// The [parameters] list and [operations] map are initialized as empty
+  /// and can be populated later using the [decode] method or by directly
+  /// adding elements.
   APIPath();
 
+  /// A list of API parameters associated with this path.
+  ///
+  /// This list contains [APIParameter] objects that define the parameters
+  /// applicable to all operations on this path. These parameters can include
+  /// path parameters, query parameters, header parameters, etc.
+  ///
+  /// Note: The list can contain null values, hence the use of [APIParameter?].
   List<APIParameter?> parameters = [];
+
+  /// A map of operation names to [APIOperation] objects for this path.
+  ///
+  /// This map contains the HTTP methods (e.g., 'get', 'post', 'put', 'delete')
+  /// as keys, and their corresponding [APIOperation] objects as values.
+  ///
+  /// Each [APIOperation] describes the details of the API operation for that
+  /// specific HTTP method on this path.
+  ///
+  /// The use of [APIOperation?] allows for null values in the map.
   Map<String, APIOperation?> operations = {};
 
+  /// Decodes the [APIPath] object from a [KeyedArchive].
+  ///
+  /// This method populates the [APIPath] object with data from the provided [KeyedArchive].
+  /// It handles the following cases:
+  /// - If a key is "$ref", it's currently not implemented (todo).
+  /// - If a key is "parameters", it decodes a list of [APIParameter] objects.
+  /// - For all other keys, it assumes they are operation names and decodes them as [APIOperation] objects.
+  ///
+  /// The decoded parameters are stored in the [parameters] list, while the operations
+  /// are stored in the [operations] map with their corresponding keys.
+  ///
+  /// [object] is the [KeyedArchive] containing the encoded [APIPath] data.
   @override
   void decode(KeyedArchive object) {
     super.decode(object);
@@ -33,6 +81,16 @@ class APIPath extends APIObject {
     }
   }
 
+  /// Encodes the [APIPath] object into a [KeyedArchive].
+  ///
+  /// This method serializes the [APIPath] object's data into the provided [KeyedArchive].
+  /// It performs the following operations:
+  /// - Calls the superclass's encode method to handle any base class properties.
+  /// - Encodes the [parameters] list into the archive under the key "parameters".
+  /// - Iterates through the [operations] map, encoding each operation into the archive
+  ///   using its operation name as the key.
+  ///
+  /// [object] is the [KeyedArchive] where the encoded data will be stored.
   @override
   void encode(KeyedArchive object) {
     super.encode(object);

packages/openapi/lib/src/v2/property.dart

@@ -11,6 +11,14 @@ import 'package:protevus_typeforge/codable.dart';
 import 'package:protevus_openapi/object.dart';
 import 'package:protevus_openapi/v2.dart';
 
+/// Represents the different types of schema representations in an API.
+///
+/// This enumeration defines the possible structural representations of an API schema:
+/// - [primitive]: Represents basic data types like strings, numbers, booleans, etc.
+/// - [array]: Represents a list or collection of items.
+/// - [object]: Represents a complex type with key-value pairs.
+/// - [structure]: Represents a structured data type (e.g., a custom object).
+/// - [unknownOrInvalid]: Represents an unknown or invalid schema representation.
 enum APISchemaRepresentation {
   primitive,
   array,
@@ -19,9 +27,40 @@ enum APISchemaRepresentation {
   unknownOrInvalid
 }
 
+/// Represents the different formats for collection parameters in API requests.
+///
+/// This enumeration defines the possible formats for serializing array parameters:
+/// - [csv]: Comma-separated values (e.g., "foo,bar,baz")
+/// - [ssv]: Space-separated values (e.g., "foo bar baz")
+/// - [tsv]: Tab-separated values (e.g., "foo\tbar\tbaz")
+/// - [pipes]: Pipe-separated values (e.g., "foo|bar|baz")
 enum APICollectionFormat { csv, ssv, tsv, pipes }
 
+/// A utility class for encoding and decoding [APICollectionFormat] values.
+///
+/// This class provides static methods to convert between string representations
+/// and [APICollectionFormat] enum values.
+/// Decodes a string representation into an [APICollectionFormat] value.
+///
+/// Takes a [String] input and returns the corresponding [APICollectionFormat],
+/// or `null` if the input doesn't match any known format.
+///
+/// - Returns [APICollectionFormat.csv] for "csv"
+/// - Returns [APICollectionFormat.ssv] for "ssv"
+/// - Returns [APICollectionFormat.tsv] for "tsv"
+/// - Returns [APICollectionFormat.pipes] for "pipes"
+/// - Returns `null` for any other input
 class APICollectionFormatCodec {
+  /// Decodes a string representation into an [APICollectionFormat] value.
+  ///
+  /// Takes a [String] input and returns the corresponding [APICollectionFormat],
+  /// or `null` if the input doesn't match any known format.
+  ///
+  /// - Returns [APICollectionFormat.csv] for "csv"
+  /// - Returns [APICollectionFormat.ssv] for "ssv"
+  /// - Returns [APICollectionFormat.tsv] for "tsv"
+  /// - Returns [APICollectionFormat.pipes] for "pipes"
+  /// - Returns `null` for any other input
   static APICollectionFormat? decode(String? location) {
     switch (location) {
       case "csv":
@@ -37,6 +76,16 @@ class APICollectionFormatCodec {
     }
   }
 
+  /// Encodes an [APICollectionFormat] value into its string representation.
+  ///
+  /// Takes an [APICollectionFormat] input and returns the corresponding string,
+  /// or `null` if the input is null or doesn't match any known format.
+  ///
+  /// - Returns "csv" for [APICollectionFormat.csv]
+  /// - Returns "ssv" for [APICollectionFormat.ssv]
+  /// - Returns "tsv" for [APICollectionFormat.tsv]
+  /// - Returns "pipes" for [APICollectionFormat.pipes]
+  /// - Returns `null` for any other input or null
   static String? encode(APICollectionFormat? location) {
     switch (location) {
       case APICollectionFormat.csv:
@@ -53,25 +102,202 @@ class APICollectionFormatCodec {
   }
 }
 
+/// Represents a property in an API schema.
+///
+/// This class extends [APIObject] and provides fields and methods to handle
+/// various aspects of an API property, including its type, format, constraints,
+/// and serialization behavior.
+///
+/// Properties:
+/// - [type]: The data type of the property (e.g., string, number, array).
+/// - [format]: Additional format information for the property.
+/// - [collectionFormat]: Format for serializing array parameters.
+/// - [defaultValue]: Default value for the property.
+/// - [maximum]: Maximum value for numeric properties.
+/// - [exclusiveMaximum]: Whether the maximum is exclusive.
+/// - [minimum]: Minimum value for numeric properties.
+/// - [exclusiveMinimum]: Whether the minimum is exclusive.
+/// - [maxLength]: Maximum length for string properties.
+/// - [minLength]: Minimum length for string properties.
+/// - [pattern]: Regular expression pattern for string properties.
+/// - [maxItems]: Maximum number of items for array properties.
+/// - [minItems]: Minimum number of items for array properties.
+/// - [uniqueItems]: Whether array items must be unique.
+/// - [multipleOf]: Numeric properties must be multiples of this value.
+/// - [enumerated]: List of allowed values for the property.
+///
+/// The [representation] getter determines the schema representation of the property.
+///
+/// This class also implements [decode] and [encode] methods for serialization
+/// and deserialization of the property data.
 class APIProperty extends APIObject {
+  /// The data type of the property.
+  ///
+  /// This field represents the primary type of the API property, such as string,
+  /// number, boolean, array, or object. It is defined as nullable to allow for
+  /// cases where the type might not be specified.
+  ///
+  /// The value is of type [APIType], which is likely an enum or similar type
+  /// defining the possible data types in the API schema.
   APIType? type;
+
+  /// The format of the property.
+  ///
+  /// This field provides additional format information for the property.
+  /// It can specify more precise data types or constraints, such as:
+  /// - For strings: "date", "date-time", "password", etc.
+  /// - For numbers: "float", "double", etc.
+  ///
+  /// The format is optional and can be null if not specified.
   String? format;
 
+  /// The format used for serializing array parameters.
+  ///
+  /// This property specifies how collection/array parameters are formatted when sent in
+  /// API requests. It is applicable only when the [type] is [APIType.array].
+  ///
+  /// Possible values are defined in the [APICollectionFormat] enum:
+  /// - [APICollectionFormat.csv]: Comma-separated values
+  /// - [APICollectionFormat.ssv]: Space-separated values
+  /// - [APICollectionFormat.tsv]: Tab-separated values
+  /// - [APICollectionFormat.pipes]: Pipe-separated values
+  ///
+  /// If not specified (null), the default format is typically comma-separated.
   APICollectionFormat? collectionFormat;
+
+  /// The default value for the property.
+  ///
+  /// This field represents the default value that should be used for the property
+  /// if no value is provided. It can be of any type (hence the 'dynamic' type),
+  /// allowing it to match the property's data type.
+  ///
+  /// The default value is optional and can be null if not specified.
   dynamic defaultValue;
+
+  /// The maximum value for numeric properties.
+  ///
+  /// This field specifies the maximum allowed value for numeric properties.
+  /// It is applicable when [type] is a numeric type (e.g., integer or number).
+  /// The value is inclusive unless [exclusiveMaximum] is set to true.
+  ///
+  /// This property is optional and can be null if not specified.
   num? maximum;
+
+  /// Indicates whether the maximum value is exclusive.
+  ///
+  /// When set to `true`, the [maximum] value is treated as an exclusive upper bound.
+  /// When `false` or `null`, the [maximum] value is inclusive.
+  ///
+  /// This property is only applicable when [maximum] is set and [type] is a numeric type.
   bool? exclusiveMaximum;
+
+  /// The minimum value for numeric properties.
+  ///
+  /// This field specifies the minimum allowed value for numeric properties.
+  /// It is applicable when [type] is a numeric type (e.g., integer or number).
+  /// The value is inclusive unless [exclusiveMinimum] is set to true.
+  ///
+  /// This property is optional and can be null if not specified.
   num? minimum;
+
+  /// Indicates whether the minimum value is exclusive.
+  ///
+  /// When set to `true`, the [minimum] value is treated as an exclusive lower bound.
+  /// When `false` or `null`, the [minimum] value is inclusive.
+  ///
+  /// This property is only applicable when [minimum] is set and [type] is a numeric type.
   bool? exclusiveMinimum;
+
+  /// The maximum length for string properties.
+  ///
+  /// This field specifies the maximum allowed length for string properties.
+  /// It is applicable when [type] is [APIType.string].
+  ///
+  /// The value is an integer representing the maximum number of characters allowed.
+  /// If not specified (null), there is no upper limit on the string length.
   int? maxLength;
+
+  /// The minimum length for string properties.
+  ///
+  /// This field specifies the minimum allowed length for string properties.
+  /// It is applicable when [type] is [APIType.string].
+  ///
+  /// The value is an integer representing the minimum number of characters required.
+  /// If not specified (null), there is no lower limit on the string length.
   int? minLength;
+
+  /// The regular expression pattern for string properties.
+  ///
+  /// This field specifies a regular expression that a string property must match.
+  /// It is applicable when [type] is [APIType.string].
+  ///
+  /// The pattern is represented as a string containing a valid regular expression.
+  /// If not specified (null), no pattern matching is enforced on the string value.
   String? pattern;
+
+  /// The maximum number of items for array properties.
+  ///
+  /// This field specifies the maximum allowed number of items in an array property.
+  /// It is applicable when [type] is [APIType.array].
+  ///
+  /// The value is an integer representing the maximum number of elements allowed in the array.
+  /// If not specified (null), there is no upper limit on the number of array items.
   int? maxItems;
+
+  /// The minimum number of items for array properties.
+  ///
+  /// This field specifies the minimum required number of items in an array property.
+  /// It is applicable when [type] is [APIType.array].
+  ///
+  /// The value is an integer representing the minimum number of elements required in the array.
+  /// If not specified (null), there is no lower limit on the number of array items.
   int? minItems;
+
+  /// Indicates whether array items must be unique.
+  ///
+  /// This field specifies whether all items in an array property must be unique.
+  /// It is applicable when [type] is [APIType.array].
+  ///
+  /// When set to `true`, all elements in the array must be unique.
+  /// When `false` or `null`, duplicate elements are allowed in the array.
+  ///
+  /// This property is optional and can be null if not specified.
   bool? uniqueItems;
+
+  /// Specifies that numeric properties must be multiples of this value.
+  ///
+  /// This field is applicable when [type] is a numeric type (e.g., integer or number).
+  /// If set, the value of the property must be divisible by this number.
+  ///
+  /// For example, if [multipleOf] is set to 2, valid values could be 0, 2, 4, -2, etc.
+  ///
+  /// This property is optional and can be null if not specified.
   num? multipleOf;
+
+  /// A list of allowed values for the property.
+  ///
+  /// This field specifies a list of valid values that the property can take.
+  /// It is applicable to properties of various types, including strings, numbers, and more.
+  ///
+  /// When set, the value of the property must be one of the items in this list.
+  /// If not specified (null), there are no restrictions on the allowed values.
+  ///
+  /// The list is of type `dynamic` to accommodate different data types that may be used
+  /// for the enumeration values, depending on the property's type.
   List<dynamic>? enumerated;
 
+  /// Determines the schema representation of the property.
+  ///
+  /// This getter analyzes the [type] of the property and returns the corresponding
+  /// [APISchemaRepresentation]:
+  /// - Returns [APISchemaRepresentation.array] if the type is [APIType.array]
+  /// - Returns [APISchemaRepresentation.object] if the type is [APIType.object]
+  /// - Returns [APISchemaRepresentation.primitive] for all other types
+  ///
+  /// This representation helps in categorizing and handling different property types
+  /// in API schemas.
+  ///
+  /// Returns: An [APISchemaRepresentation] value indicating the schema representation.
   APISchemaRepresentation get representation {
     if (type == APIType.array) {
       return APISchemaRepresentation.array;
@@ -82,6 +308,21 @@ class APIProperty extends APIObject {
     return APISchemaRepresentation.primitive;
   }
 
+  /// Decodes the property information from a [KeyedArchive] object.
+  ///
+  /// This method populates the fields of the [APIProperty] instance with values
+  /// decoded from the given [KeyedArchive] object. It decodes various properties
+  /// such as type, format, constraints, and other metadata associated with the API property.
+  ///
+  /// The method first calls the superclass's decode method, then decodes specific
+  /// fields for the [APIProperty] class. Each field is extracted from the archive
+  /// using its corresponding key.
+  ///
+  /// Parameters:
+  ///   [object] - A [KeyedArchive] containing the encoded property information.
+  ///
+  /// Note: This method assumes that the [KeyedArchive] contains keys matching
+  /// the property names of the [APIProperty] class.
   @override
   void decode(KeyedArchive object) {
     super.decode(object);
@@ -105,6 +346,21 @@ class APIProperty extends APIObject {
     enumerated = object.decode("enum");
   }
 
+  /// Encodes the property information into a [KeyedArchive] object.
+  ///
+  /// This method serializes the fields of the [APIProperty] instance into the given
+  /// [KeyedArchive] object. It encodes various properties such as type, format,
+  /// constraints, and other metadata associated with the API property.
+  ///
+  /// The method first calls the superclass's encode method, then encodes specific
+  /// fields of the [APIProperty] class. Each field is added to the archive
+  /// using its corresponding key.
+  ///
+  /// Parameters:
+  ///   [object] - A [KeyedArchive] to store the encoded property information.
+  ///
+  /// Note: This method encodes all fields of the [APIProperty] class, including
+  /// null values. The receiving end should handle potential null values appropriately.
   @override
   void encode(KeyedArchive object) {
     super.encode(object);

packages/openapi/lib/src/v2/response.dart

@@ -12,13 +12,65 @@ import 'package:protevus_openapi/object.dart';
 import 'package:protevus_openapi/v2.dart';
 
 /// Represents an HTTP response in the OpenAPI specification.
+///
+/// This class extends [APIObject] and provides properties and methods to
+/// handle the response description, schema, and headers.
+///
+/// Properties:
+/// - [description]: A string describing the response.
+/// - [schema]: An [APISchemaObject] representing the structure of the response body.
+/// - [headers]: A map of response headers, where keys are header names and values are [APIHeader] objects.
+///
+/// The class includes methods for encoding and decoding the response object
+/// to and from a [KeyedArchive].
 class APIResponse extends APIObject {
+  /// Creates a new instance of [APIResponse].
+  ///
+  /// This constructor initializes a new [APIResponse] object with default values.
+  /// The [description] is set to an empty string, [schema] is null,
+  /// and [headers] is an empty map.
   APIResponse();
 
+  /// A string describing the response.
+  ///
+  /// This property holds a brief description of the API response.
+  /// It provides context about what the response represents or contains.
+  /// The description is optional and defaults to an empty string if not specified.
   String? description = "";
+
+  /// Represents the structure of the response body.
+  ///
+  /// This property is of type [APISchemaObject] and defines the schema
+  /// for the response payload. It describes the structure, types, and
+  /// constraints of the data returned in the response body.
+  ///
+  /// The schema can be null if the response doesn't have a body or if
+  /// the schema is not defined in the API specification.
   APISchemaObject? schema;
+
+  /// A map of response headers.
+  ///
+  /// This property is a [Map] where the keys are header names (strings) and the values
+  /// are [APIHeader] objects or null. It represents the headers that are expected
+  /// to be included in the API response.
+  ///
+  /// The map is nullable and initialized as an empty map by default. Each header
+  /// in the map can also be null, allowing for optional headers in the response.
   Map<String, APIHeader?>? headers = {};
 
+  /// Decodes the [APIResponse] object from a [KeyedArchive].
+  ///
+  /// This method overrides the [decode] method from the superclass and is responsible
+  /// for populating the properties of the [APIResponse] object from the given [KeyedArchive].
+  ///
+  /// It performs the following actions:
+  /// 1. Calls the superclass's decode method.
+  /// 2. Decodes the 'description' field into the [description] property.
+  /// 3. Decodes the 'schema' field into the [schema] property, creating a new [APISchemaObject] if necessary.
+  /// 4. Decodes the 'headers' field into the [headers] property, creating new [APIHeader] objects as needed.
+  ///
+  /// Parameters:
+  /// - [object]: A [KeyedArchive] containing the encoded data for the [APIResponse].
   @override
   void decode(KeyedArchive object) {
     super.decode(object);
@@ -28,6 +80,19 @@ class APIResponse extends APIObject {
     headers = object.decodeObjectMap("headers", () => APIHeader());
   }
 
+  /// Encodes the [APIResponse] object into a [KeyedArchive].
+  ///
+  /// This method overrides the [encode] method from the superclass and is responsible
+  /// for encoding the properties of the [APIResponse] object into the given [KeyedArchive].
+  ///
+  /// It performs the following actions:
+  /// 1. Calls the superclass's encode method.
+  /// 2. Encodes the [headers] property into the 'headers' field of the archive.
+  /// 3. Encodes the [schema] property into the 'schema' field of the archive.
+  /// 4. Encodes the [description] property into the 'description' field of the archive.
+  ///
+  /// Parameters:
+  /// - [object]: A [KeyedArchive] to store the encoded data of the [APIResponse].
   @override
   void encode(KeyedArchive object) {
     super.encode(object);

packages/openapi/lib/src/v2/schema.dart

@@ -12,24 +12,141 @@ import 'package:protevus_typeforge/codable.dart';
 import 'package:protevus_openapi/v2.dart';
 
 /// Represents a schema object in the OpenAPI specification.
+///
+/// This class extends [APIProperty] and provides additional properties and methods
+/// specific to schema objects in the OpenAPI specification.
+///
+/// Properties:
+/// - [title]: A string representing the title of the schema.
+/// - [description]: A string describing the schema.
+/// - [example]: An example value for the schema.
+/// - [isRequired]: A list of required properties.
+/// - [readOnly]: A boolean indicating if the schema is read-only.
+/// - [items]: An [APISchemaObject] representing array items (valid when type is array).
+/// - [properties]: A map of property names to [APISchemaObject]s (valid when type is null).
+/// - [additionalProperties]: An [APISchemaObject] for additional properties (valid when type is object).
+///
+/// Methods:
+/// - [representation]: Returns the [APISchemaRepresentation] of the schema.
+/// - [decode]: Decodes the schema from a [KeyedArchive].
+/// - [encode]: Encodes the schema to a [KeyedArchive].
+///
+/// This class also overrides the [castMap] getter to provide custom casting for the 'required' field.
 class APISchemaObject extends APIProperty {
+  /// Default constructor for APISchemaObject.
+  ///
+  /// Creates a new instance of APISchemaObject with default values.
+  /// This constructor doesn't take any parameters and initializes
+  /// the object with its default state.
   APISchemaObject();
 
+  /// The title of the schema.
+  ///
+  /// This property represents the title of the schema object.
+  /// It can be null if no title is specified.
   String? title;
+
+  /// A description of the schema.
+  ///
+  /// This property provides a detailed explanation of the schema object.
+  /// It can be null if no description is specified.
   String? description;
+
+  /// An example value for the schema.
+  ///
+  /// This property holds an example value that represents the schema.
+  /// It can be of any type (String, int, bool, Map, List, etc.) depending on the schema definition.
+  /// The example is used to provide a clear illustration of what data conforming to the schema might look like.
+  /// This property can be null if no example is specified.
   String? example;
+
+  /// A list of required properties for this schema object.
+  ///
+  /// This list contains the names of properties that are required
+  /// for this schema to be valid. Each element is a String representing
+  /// a property name. The list can be empty if no properties are required,
+  /// or it can be null if the required properties are not specified.
+  ///
+  /// Note: The list allows null values, though typically all elements
+  /// should be non-null property names.
   List<String?>? isRequired = [];
+
+  /// Indicates whether the schema is read-only.
+  ///
+  /// When set to true, it specifies that the schema should be treated as read-only,
+  /// meaning it can be retrieved and read, but should not be modified or updated.
+  /// This is particularly useful for properties that are auto-generated or controlled by the system.
+  ///
+  /// Defaults to false, indicating that the schema is writable by default.
   bool readOnly = false;
 
-  /// Valid when type == array
+  /// Represents the schema for array items when the type is 'array'.
+  ///
+  /// This property is only applicable when the schema's type is set to 'array'.
+  /// It defines the schema for the items within the array.
+  ///
+  /// - If [items] is null, it means the array items have no specific schema defined.
+  /// - If [items] is set, it provides the schema that all items in the array must conform to.
+  ///
+  /// Example:
+  /// If this schema represents an array of strings, [items] would be an APISchemaObject
+  /// with its type set to 'string'.
   APISchemaObject? items;
 
-  /// Valid when type == null
+  /// A map of property names to their corresponding schema objects.
+  ///
+  /// This property is valid when the schema's type is null or 'object'.
+  /// It defines the structure of an object by specifying the schemas of its properties.
+  ///
+  /// The keys in the map are strings representing property names.
+  /// The values are [APISchemaObject] instances that define the schema for each property.
+  ///
+  /// This property can be null if no properties are defined, or if the schema
+  /// represents a type other than an object.
+  ///
+  /// Example:
+  /// ```dart
+  /// properties = {
+  ///   "name": APISchemaObject()..type = "string",
+  ///   "age": APISchemaObject()..type = "integer"
+  /// };
+  /// ```
   Map<String, APISchemaObject?>? properties;
 
+  /// Represents the schema for additional properties when the type is 'object'.
+  ///
+  /// This property is applicable when the schema's type is set to 'object'.
+  /// It defines the schema for any additional properties that are not explicitly defined
+  /// in the [properties] map.
+  ///
+  /// - If [additionalProperties] is null, it means additional properties are not allowed.
+  /// - If [additionalProperties] is set to an [APISchemaObject], it specifies the schema
+  ///   that any additional properties must conform to.
+  ///
+  /// This property allows for flexible object structures where some properties are
+  /// explicitly defined, while others can follow a general schema.
+  ///
+  /// Example:
+  /// If set to an [APISchemaObject] with type "string", it means any additional
+  /// properties not listed in [properties] must have string values.
+  ///
   /// Valid when type == object
   APISchemaObject? additionalProperties;
 
+  /// Returns the representation of this schema object.
+  ///
+  /// This method overrides the base [representation] getter to provide
+  /// specific behavior for schema objects with properties.
+  ///
+  /// If the [properties] map is not null, it indicates that this schema
+  /// represents a structured object, so it returns [APISchemaRepresentation.structure].
+  ///
+  /// If [properties] is null, it falls back to the superclass implementation
+  /// to determine the representation based on other attributes of the schema.
+  ///
+  /// Returns:
+  ///   [APISchemaRepresentation.structure] if [properties] is not null,
+  ///   otherwise returns the result of the superclass [representation] getter.
   @override
   APISchemaRepresentation get representation {
     if (properties != null) {
@@ -39,10 +156,45 @@ class APISchemaObject extends APIProperty {
     return super.representation;
   }
 
+  /// Overrides the [castMap] getter to provide custom casting for the 'required' field.
+  ///
+  /// This getter returns a Map that defines how certain fields should be cast
+  /// when encoding or decoding the object. Specifically:
+  ///
+  /// - The 'required' field is cast to a List of strings.
+  ///
+  /// This ensures that the 'required' field, which represents the list of required
+  /// properties for this schema object, is always treated as a list of strings,
+  /// even if the incoming data might have a different format.
+  ///
+  /// Returns:
+  ///   A Map where the key is the field name ('required') and the value is a Cast
+  ///   object specifying how to cast the field (List of strings in this case).
   @override
   Map<String, cast.Cast> get castMap =>
       {"required": const cast.List(cast.string)};
 
+  /// Decodes the APISchemaObject from a KeyedArchive.
+  ///
+  /// This method overrides the base [decode] method to provide custom decoding
+  /// for APISchemaObject properties. It populates the object's fields from the
+  /// provided [KeyedArchive] object.
+  ///
+  /// Parameters:
+  /// - [object]: A [KeyedArchive] containing the encoded data for this schema object.
+  ///
+  /// The method decodes the following properties:
+  /// - title: The schema's title (String)
+  /// - description: The schema's description (String)
+  /// - isRequired: List of required properties (List<String?>)
+  /// - example: An example value for the schema (String)
+  /// - readOnly: Whether the schema is read-only (bool, defaults to false)
+  /// - items: The schema for array items (APISchemaObject)
+  /// - additionalProperties: The schema for additional properties (APISchemaObject)
+  /// - properties: A map of property names to their schemas (Map<String, APISchemaObject?>)
+  ///
+  /// Note: This method calls the superclass [decode] method first to handle any
+  /// decoding defined in the parent class.
   @override
   void decode(KeyedArchive object) {
     super.decode(object);
@@ -59,6 +211,27 @@ class APISchemaObject extends APIProperty {
     properties = object.decodeObjectMap("properties", () => APISchemaObject());
   }
 
+  /// Encodes the APISchemaObject into a KeyedArchive.
+  ///
+  /// This method overrides the base [encode] method to provide custom encoding
+  /// for APISchemaObject properties. It serializes the object's fields into the
+  /// provided [KeyedArchive] object.
+  ///
+  /// Parameters:
+  /// - [object]: A [KeyedArchive] where the encoded data for this schema object will be stored.
+  ///
+  /// The method encodes the following properties:
+  /// - title: The schema's title (String)
+  /// - description: The schema's description (String)
+  /// - isRequired: List of required properties (List<String?>)
+  /// - example: An example value for the schema (String)
+  /// - readOnly: Whether the schema is read-only (bool)
+  /// - items: The schema for array items (APISchemaObject)
+  /// - additionalProperties: The schema for additional properties (APISchemaObject)
+  /// - properties: A map of property names to their schemas (Map<String, APISchemaObject?>)
+  ///
+  /// Note: This method calls the superclass [encode] method first to handle any
+  /// encoding defined in the parent class.
   @override
   void encode(KeyedArchive object) {
     super.encode(object);

packages/openapi/lib/src/v2/security.dart

@@ -13,6 +13,17 @@ import 'package:protevus_openapi/object.dart';
 import 'package:protevus_openapi/v2.dart';
 
 /// Represents a OAuth 2.0 security scheme flow in the OpenAPI specification.
+///
+/// This enum defines the different types of OAuth 2.0 flows that can be used
+/// in an OpenAPI security scheme. The available flows are:
+///
+/// - [implicit]: The implicit grant flow.
+/// - [password]: The resource owner password credentials grant flow.
+/// - [application]: The client credentials grant flow.
+/// - [authorizationCode]: The authorization code grant flow.
+///
+/// These flows correspond to the standard OAuth 2.0 grant types as defined
+/// in RFC 6749.
 enum APISecuritySchemeFlow {
   implicit,
   password,
@@ -20,7 +31,28 @@ enum APISecuritySchemeFlow {
   authorizationCode
 }
 
+/// A utility class for encoding and decoding [APISecuritySchemeFlow] values.
+///
+/// This class provides static methods to convert between [APISecuritySchemeFlow] enum values
+/// and their corresponding string representations used in the OpenAPI specification.
 class APISecuritySchemeFlowCodec {
+  /// Decodes a string representation of an OAuth 2.0 flow into an [APISecuritySchemeFlow] enum value.
+  ///
+  /// This method takes a [String] parameter [flow] and returns the corresponding
+  /// [APISecuritySchemeFlow] enum value. If the input string doesn't match any
+  /// known flow, the method returns null.
+  ///
+  /// The mapping is as follows:
+  /// - "accessCode" -> [APISecuritySchemeFlow.authorizationCode]
+  /// - "password" -> [APISecuritySchemeFlow.password]
+  /// - "implicit" -> [APISecuritySchemeFlow.implicit]
+  /// - "application" -> [APISecuritySchemeFlow.application]
+  ///
+  /// Parameters:
+  ///   [flow]: A string representation of the OAuth 2.0 flow.
+  ///
+  /// Returns:
+  ///   The corresponding [APISecuritySchemeFlow] enum value, or null if no match is found.
   static APISecuritySchemeFlow? decode(String? flow) {
     switch (flow) {
       case "accessCode":
@@ -36,6 +68,23 @@ class APISecuritySchemeFlowCodec {
     }
   }
 
+  /// Encodes an [APISecuritySchemeFlow] enum value into its string representation.
+  ///
+  /// This method takes an [APISecuritySchemeFlow] enum value as input and returns
+  /// the corresponding string representation used in the OpenAPI specification.
+  /// If the input is null or doesn't match any known flow, the method returns null.
+  ///
+  /// The mapping is as follows:
+  /// - [APISecuritySchemeFlow.authorizationCode] -> "accessCode"
+  /// - [APISecuritySchemeFlow.password] -> "password"
+  /// - [APISecuritySchemeFlow.implicit] -> "implicit"
+  /// - [APISecuritySchemeFlow.application] -> "application"
+  ///
+  /// Parameters:
+  ///   [flow]: An [APISecuritySchemeFlow] enum value to be encoded.
+  ///
+  /// Returns:
+  ///   The string representation of the OAuth 2.0 flow, or null if no match is found.
   static String? encode(APISecuritySchemeFlow? flow) {
     switch (flow) {
       case APISecuritySchemeFlow.authorizationCode:
@@ -53,17 +102,98 @@ class APISecuritySchemeFlowCodec {
 }
 
 /// Represents a security scheme in the OpenAPI specification.
+///
+/// This class defines various types of security schemes that can be used in an OpenAPI document.
+/// It supports three main types of security schemes:
+/// 1. Basic Authentication
+/// 2. API Key
+/// 3. OAuth2
+///
+/// The class provides constructors for each type of security scheme and methods to encode and decode
+/// the security scheme information to and from a KeyedArchive object.
+///
+/// Properties:
+/// - [type]: The type of the security scheme (e.g., "basic", "apiKey", "oauth2").
+/// - [description]: An optional description of the security scheme.
+/// - [apiKeyName]: The name of the API key (for API Key type).
+/// - [apiKeyLocation]: The location of the API key (for API Key type).
+/// - [oauthFlow]: The OAuth2 flow type (for OAuth2 type).
+/// - [authorizationURL]: The authorization URL (for OAuth2 type).
+/// - [tokenURL]: The token URL (for OAuth2 type).
+/// - [scopes]: A map of available scopes (for OAuth2 type).
+///
+/// The class also includes utility methods and properties:
+/// - [isOAuth2]: A getter that returns true if the security scheme is OAuth2.
+/// - [castMap]: Provides casting information for the 'scopes' property.
+/// - [decode]: Decodes the security scheme information from a KeyedArchive object.
+/// - [encode]: Encodes the security scheme information into a KeyedArchive object.
 class APISecurityScheme extends APIObject {
+  /// Default constructor for the [APISecurityScheme] class.
+  ///
+  /// This constructor creates an instance of [APISecurityScheme] without initializing any specific properties.
+  /// It's typically used when you want to create a security scheme object and set its properties manually later.
   APISecurityScheme();
 
+  /// Creates a basic authentication security scheme.
+  ///
+  /// This constructor initializes an [APISecurityScheme] instance
+  /// with the type set to "basic", representing HTTP Basic Authentication.
+  /// Basic Authentication allows API clients to authenticate by providing
+  /// their username and password.
+  ///
+  /// Example usage:
+  /// ```dart
+  /// var basicAuth = APISecurityScheme.basic();
+  /// ```
   APISecurityScheme.basic() {
     type = "basic";
   }
 
+  /// Creates an API Key security scheme.
+  ///
+  /// This constructor initializes an [APISecurityScheme] instance
+  /// with the type set to "apiKey". It requires two parameters:
+  ///
+  /// - [apiKeyName]: The name of the API key to be used for authentication.
+  /// - [apiKeyLocation]: The location where the API key should be included in the request,
+  ///   typically specified as a value from the [APIParameterLocation] enum.
+  ///
+  /// API Key authentication allows API clients to authenticate by including a specific
+  /// key in their requests, either in the header, query parameters, or cookies.
+  ///
+  /// Example usage:
+  /// ```dart
+  /// var apiKeyAuth = APISecurityScheme.apiKey('X-API-Key', APIParameterLocation.header);
+  /// ```
   APISecurityScheme.apiKey(this.apiKeyName, this.apiKeyLocation) {
     type = "apiKey";
   }
 
+  /// Creates an OAuth2 security scheme.
+  ///
+  /// This constructor initializes an [APISecurityScheme] instance
+  /// with the type set to "oauth2". It requires one mandatory parameter:
+  ///
+  /// - [oauthFlow]: The OAuth2 flow type, specified as an [APISecuritySchemeFlow] enum value.
+  ///
+  /// Optional parameters include:
+  ///
+  /// - [authorizationURL]: The authorization URL for the OAuth2 flow.
+  /// - [tokenURL]: The token URL for the OAuth2 flow.
+  /// - [scopes]: A map of available scopes for the OAuth2 flow. Defaults to an empty map.
+  ///
+  /// OAuth2 allows API clients to obtain limited access to user accounts on an HTTP service,
+  /// either on behalf of a user or on behalf of the client itself.
+  ///
+  /// Example usage:
+  /// ```dart
+  /// var oauth2Auth = APISecurityScheme.oauth2(
+  ///   APISecuritySchemeFlow.authorizationCode,
+  ///   authorizationURL: 'https://example.com/oauth/authorize',
+  ///   tokenURL: 'https://example.com/oauth/token',
+  ///   scopes: {'read': 'Read access', 'write': 'Write access'}
+  /// );
+  /// ```
   APISecurityScheme.oauth2(
     this.oauthFlow, {
     this.authorizationURL,
@@ -73,14 +203,62 @@ class APISecurityScheme extends APIObject {
     type = "oauth2";
   }
 
+  /// The type of the security scheme.
+  ///
+  /// This property specifies the type of the security scheme. It can be one of:
+  /// - "basic" for Basic Authentication
+  /// - "apiKey" for API Key Authentication
+  /// - "oauth2" for OAuth2 Authentication
+  ///
+  /// This field is required and must be set for the security scheme to be valid.
   late String type;
+
+  /// A description of the security scheme.
+  ///
+  /// This optional property provides additional information about the security scheme.
+  /// It can be used to explain how the security scheme works, its purpose, or any
+  /// specific requirements for using it.
+  ///
+  /// The value is a string that can contain multiple lines of text if needed.
+  /// If not specified, this property will be null.
   String? description;
 
-  // API Key
+  /// The name of the API key for API Key authentication.
+  ///
+  /// This property is used when the security scheme type is "apiKey".
+  /// It specifies the name of the API key that should be used in the request.
+  /// For example, if set to "X-API-Key", the client would need to include
+  /// this header in their request: "X-API-Key: <actual-api-key-value>".
+  ///
+  /// This property is nullable and will be null for non-API Key security schemes.
   String? apiKeyName;
+
+  /// The location of the API key in the request.
+  ///
+  /// This property specifies where the API key should be included in the request
+  /// when using API Key authentication. It can be one of the following:
+  /// - [APIParameterLocation.query] for including the key in the query parameters
+  /// - [APIParameterLocation.header] for including the key in the request headers
+  /// - [APIParameterLocation.cookie] for including the key in a cookie
+  ///
+  /// This property is nullable and will be null for non-API Key security schemes.
+  /// It is typically used in conjunction with [apiKeyName] to define how an API key
+  /// should be sent with requests.
   APIParameterLocation? apiKeyLocation;
 
-  // Oauth2
+  /// The OAuth2 flow type for this security scheme.
+  ///
+  /// This property specifies the type of OAuth2 flow used when the security scheme
+  /// is of type "oauth2". It is represented by the [APISecuritySchemeFlow] enum,
+  /// which can have one of the following values:
+  /// - [APISecuritySchemeFlow.implicit]
+  /// - [APISecuritySchemeFlow.password]
+  /// - [APISecuritySchemeFlow.application]
+  /// - [APISecuritySchemeFlow.authorizationCode]
+  ///
+  /// This property is nullable and will be null for non-OAuth2 security schemes.
+  /// It is used in conjunction with other OAuth2-specific properties like
+  /// [authorizationURL], [tokenURL], and [scopes] to fully define the OAuth2 flow.
   APISecuritySchemeFlow? oauthFlow;
   String? authorizationURL;
   String? tokenURL;
@@ -90,10 +268,40 @@ class APISecurityScheme extends APIObject {
     return type == "oauth2";
   }
 
+  /// Provides a mapping of property names to their respective casting functions.
+  ///
+  /// This getter overrides the base class implementation to specify custom casting
+  /// behavior for the 'scopes' property of the [APISecurityScheme] class.
+  ///
+  /// Returns:
+  ///   A [Map] where the key is the property name ('scopes') and the value is a [cast.Cast]
+  ///   object that defines how to cast the property's value. In this case, it specifies
+  ///   that 'scopes' should be cast as a Map with string keys and string values.
   @override
   Map<String, cast.Cast> get castMap =>
       {"scopes": const cast.Map(cast.string, cast.string)};
 
+  /// Decodes the security scheme information from a [KeyedArchive] object.
+  ///
+  /// This method populates the properties of the [APISecurityScheme] instance
+  /// based on the data stored in the provided [KeyedArchive] object. It handles
+  /// different types of security schemes (basic, OAuth2, and API key) and
+  /// decodes their specific properties accordingly.
+  ///
+  /// The method performs the following tasks:
+  /// 1. Calls the superclass's decode method.
+  /// 2. Decodes the 'type' and 'description' properties.
+  /// 3. Based on the 'type', decodes additional properties:
+  ///    - For 'basic', no additional properties are decoded.
+  ///    - For 'oauth2', decodes 'flow', 'authorizationUrl', 'tokenUrl', and 'scopes'.
+  ///    - For 'apiKey', decodes 'name' and 'in' (location) properties.
+  ///
+  /// Parameters:
+  ///   [object]: A [KeyedArchive] containing the encoded security scheme information.
+  ///
+  /// Note: This method assumes that the 'scopes' property, when present, is
+  /// a non-null Map<String, String>. It will throw an error if this assumption
+  /// is not met.
   @override
   void decode(KeyedArchive object) {
     super.decode(object);
@@ -114,6 +322,27 @@ class APISecurityScheme extends APIObject {
     }
   }
 
+  /// Encodes the security scheme information into a [KeyedArchive] object.
+  ///
+  /// This method serializes the properties of the [APISecurityScheme] instance
+  /// into the provided [KeyedArchive] object. It handles different types of
+  /// security schemes (basic, OAuth2, and API key) and encodes their specific
+  /// properties accordingly.
+  ///
+  /// The method performs the following tasks:
+  /// 1. Calls the superclass's encode method.
+  /// 2. Encodes the 'type' and 'description' properties.
+  /// 3. Based on the 'type', encodes additional properties:
+  ///    - For 'basic', no additional properties are encoded.
+  ///    - For 'apiKey', encodes 'name' and 'in' (location) properties.
+  ///    - For 'oauth2', encodes 'flow', 'authorizationUrl', 'tokenUrl', and 'scopes'.
+  ///
+  /// Parameters:
+  ///   [object]: A [KeyedArchive] to store the encoded security scheme information.
+  ///
+  /// Note: This method assumes that all required properties for each security
+  /// scheme type are properly set. It's the responsibility of the caller to
+  /// ensure that the object is in a valid state before encoding.
   @override
   void encode(KeyedArchive object) {
     super.encode(object);

packages/openapi/lib/src/v2/types.dart

@@ -7,9 +7,33 @@
  * file that was distributed with this source code.
  */
 
+/// Represents the different data types used in API responses and requests.
+///
+/// This enum defines the following types:
+/// - [string]: Represents textual data.
+/// - [number]: Represents numeric data, including floating-point numbers.
+/// - [integer]: Represents whole number values.
+/// - [boolean]: Represents true/false values.
+/// - [array]: Represents a collection of values.
+/// - [file]: Represents file data.
+/// - [object]: Represents complex structured data.
 enum APIType { string, number, integer, boolean, array, file, object }
 
+/// A utility class for encoding and decoding [APIType] values.
+///
+/// This class provides static methods to convert between [APIType] enum values
+/// and their corresponding string representations.
 class APITypeCodec {
+  /// Decodes a string representation of an API type into its corresponding [APIType] enum value.
+  ///
+  /// This method takes a [String] parameter [type] and returns the matching [APIType] enum value.
+  /// If the input string doesn't match any known API type, the method returns null.
+  ///
+  /// Parameters:
+  ///   [type]: A string representation of the API type.
+  ///
+  /// Returns:
+  ///   The corresponding [APIType] enum value, or null if no match is found.
   static APIType? decode(String? type) {
     switch (type) {
       case "string":
@@ -30,6 +54,16 @@ class APITypeCodec {
     return null;
   }
 
+  /// Encodes an [APIType] enum value into its corresponding string representation.
+  ///
+  /// This method takes an [APIType] parameter [type] and returns the matching string representation.
+  /// If the input [APIType] is null or doesn't match any known API type, the method returns null.
+  ///
+  /// Parameters:
+  ///   [type]: An [APIType] enum value.
+  ///
+  /// Returns:
+  ///   The corresponding string representation of the [APIType], or null if no match is found or input is null.
   static String? encode(APIType? type) {
     switch (type) {
       case APIType.string:

packages/openapi/lib/src/v3/callback.dart

@@ -11,18 +11,52 @@ import 'package:protevus_typeforge/codable.dart';
 import 'package:protevus_openapi/object.dart';
 import 'package:protevus_openapi/v3.dart';
 
-/// A map of possible out-of band callbacks related to the parent operation.
+/// Represents a callback object in an OpenAPI specification.
 ///
 /// Each value in the map is a [APIPath] that describes a set of requests that may be initiated by the API provider and the expected responses. The key value used to identify the callback object is an expression, evaluated at runtime, that identifies a URL to use for the callback operation.
 class APICallback extends APIObject {
+  /// Creates an [APICallback] instance.
+  ///
+  /// [paths] is an optional parameter that represents the callback paths.
+  /// Each key in the [paths] map is a runtime expression that identifies the URL
+  /// to be used for the callback request, and the corresponding value is an [APIPath]
+  /// object describing the set of requests and expected responses.
   APICallback({this.paths});
+
+  /// Creates an empty [APICallback] instance.
+  ///
+  /// This constructor initializes an [APICallback] with no paths.
+  /// It can be used when you need to create an empty callback object
+  /// that will be populated later.
   APICallback.empty();
 
   /// Callback paths.
   ///
   /// The key that identifies the [APIPath] is a runtime expression that can be evaluated in the context of a runtime HTTP request/response to identify the URL to be used for the callback request. A simple example might be $request.body#/url.
+  ///
+  /// This map represents the various callback paths available in the API callback.
+  /// Each entry in the map consists of:
+  /// - A key (String): A runtime expression that identifies the URL for the callback request.
+  /// - A value (APIPath): An object describing the set of requests and expected responses for that callback URL.
+  ///
+  /// The map can be null if no callback paths are defined.
   Map<String, APIPath>? paths;
 
+  /// Decodes the [APICallback] object from a [KeyedArchive].
+  ///
+  /// This method overrides the `decode` method from the superclass and performs the following steps:
+  /// 1. Calls the superclass's `decode` method.
+  /// 2. Initializes the `paths` map.
+  /// 3. Iterates through each key-value pair in the `object`.
+  /// 4. For each pair, it checks if the value is a [KeyedArchive].
+  /// 5. If it's not a [KeyedArchive], it throws an [ArgumentError].
+  /// 6. If it is a [KeyedArchive], it decodes the value into an [APIPath] object and adds it to the `paths` map.
+  ///
+  /// Throws:
+  ///   - [ArgumentError] if any value in the callback is not an object.
+  ///
+  /// Parameters:
+  ///   - object: The [KeyedArchive] to decode from.
   @override
   void decode(KeyedArchive object) {
     super.decode(object);
@@ -38,6 +72,17 @@ class APICallback extends APIObject {
     });
   }
 
+  /// Encodes the [APICallback] object into a [KeyedArchive].
+  ///
+  /// This method overrides the `encode` method from the superclass.
+  /// Currently, this method is not implemented and will throw a [StateError]
+  /// when called.
+  ///
+  /// Parameters:
+  ///   - object: The [KeyedArchive] to encode into.
+  ///
+  /// Throws:
+  ///   - [StateError] with the message "APICallback.encode: not yet implemented."
   @override
   void encode(KeyedArchive object) {
     super.encode(object);

packages/openapi/lib/src/v3/components.dart

@@ -12,40 +12,79 @@ import 'package:protevus_openapi/object.dart';
 import 'package:protevus_openapi/util.dart';
 import 'package:protevus_openapi/v3.dart';
 
-/// Holds a set of reusable objects for different aspects of the OAS.
+/// Represents the Components Object as defined in the OpenAPI Specification.
 ///
 /// All objects defined within the components object will have no effect on the API unless they are explicitly referenced from properties outside the components object.
 class APIComponents extends APIObject {
+  /// Default constructor for APIComponents.
+  ///
+  /// Creates a new instance of APIComponents with default (empty) values for all properties.
   APIComponents();
 
+  /// Creates an empty instance of APIComponents.
+  ///
+  /// This constructor initializes an APIComponents object with no pre-defined components.
+  /// All component maps (schemas, responses, parameters, etc.) will be empty.
   APIComponents.empty();
 
-  /// An object to hold reusable [APISchemaObject?].
+  /// An object to hold reusable [APISchemaObject?] instances.
+  ///
+  /// This map stores reusable schema objects defined in the components section of an OpenAPI document.
+  /// The keys are unique names for the schemas, and the values are the corresponding [APISchemaObject] instances.
+  /// These schemas can be referenced throughout the API specification using $ref syntax.
   Map<String, APISchemaObject> schemas = {};
 
-  /// An object to hold reusable [APIResponse?].
+  /// An object to hold reusable [APIResponse?] instances.
+  ///
+  /// This map stores reusable response objects defined in the components section of an OpenAPI document.
+  /// The keys are unique names for the responses, and the values are the corresponding [APIResponse] instances.
+  /// These responses can be referenced throughout the API specification using $ref syntax.
   Map<String, APIResponse> responses = {};
 
-  /// An object to hold reusable [APIParameter?].
+  /// An object to hold reusable [APIParameter?] instances.
+  ///
+  /// This map stores reusable parameter objects defined in the components section of an OpenAPI document.
+  /// The keys are unique names for the parameters, and the values are the corresponding [APIParameter] instances.
+  /// These parameters can be referenced throughout the API specification using $ref syntax.
   Map<String, APIParameter> parameters = {};
 
-  //Map<String, APIExample> examples = {};
+  /// remove?
+  ///Map<String, APIExample> examples = {};
 
-  /// An object to hold reusable [APIRequestBody?].
+  /// An object to hold reusable [APIRequestBody] instances.
+  ///
+  /// This map stores reusable request body objects defined in the components section of an OpenAPI document.
+  /// The keys are unique names for the request bodies, and the values are the corresponding [APIRequestBody] instances.
+  /// These request bodies can be referenced throughout the API specification using $ref syntax.
   Map<String, APIRequestBody> requestBodies = {};
 
-  /// An object to hold reusable [APIHeader].
+  /// An object to hold reusable [APIHeader] instances.
+  ///
+  /// This map stores reusable header objects defined in the components section of an OpenAPI document.
+  /// The keys are unique names for the headers, and the values are the corresponding [APIHeader] instances.
+  /// These headers can be referenced throughout the API specification using $ref syntax.
   Map<String, APIHeader> headers = {};
 
-  /// An object to hold reusable [APISecurityScheme?].
+  /// An object to hold reusable [APISecurityScheme] instances.
+  ///
+  /// This map stores reusable security scheme objects defined in the components section of an OpenAPI document.
+  /// The keys are unique names for the security schemes, and the values are the corresponding [APISecurityScheme] instances.
+  /// These security schemes can be referenced throughout the API specification using $ref syntax.
+  /// They define the security mechanisms that can be used across the API.
   Map<String, APISecurityScheme> securitySchemes = {};
 
-  //Map<String, APILink> links = {};
+  /// remove?
+  ///Map<String, APILink> links = {};
 
-  /// An object to hold reusable [APICallback?].
+  /// An object to hold reusable [APICallback] instances.
+  ///
+  /// This map stores reusable callback objects defined in the components section of an OpenAPI document.
+  /// The keys are unique names for the callbacks, and the values are the corresponding [APICallback] instances.
+  /// These callbacks can be referenced throughout the API specification using $ref syntax.
+  /// Callbacks are used to define webhook-like behavior where the API can make calls back to the client.
   Map<String, APICallback> callbacks = {};
 
-  /// Returns a component definition for [uri].
+  /// Resolves a component definition based on the provided URI.
   ///
   /// Construct [uri] as a path, e.g. `Uri(path: /components/schemas/name)`.
   APIObject? resolveUri(Uri uri) {
@@ -98,6 +137,19 @@ class APIComponents extends APIObject {
     return result;
   }
 
+  /// Resolves a reference object to its corresponding component in the API specification.
+  ///
+  /// This method takes a reference object of type [T] (which must extend [APIObject])
+  /// and resolves it to the actual component it refers to within the API components.
+  ///
+  /// Parameters:
+  ///   [refObject]: The reference object to resolve. Must have a non-null [referenceURI].
+  ///
+  /// Returns:
+  ///   The resolved component object of type [T], or null if the reference couldn't be resolved.
+  ///
+  /// Throws:
+  ///   [ArgumentError] if the provided [refObject] is not a reference (i.e., has a null [referenceURI]).
   T? resolve<T extends APIObject>(T refObject) {
     if (refObject.referenceURI == null) {
       throw ArgumentError("APIObject is not a reference to a component.");
@@ -106,6 +158,22 @@ class APIComponents extends APIObject {
     return resolveUri(refObject.referenceURI!) as T?;
   }
 
+  /// Decodes the APIComponents object from a KeyedArchive.
+  ///
+  /// This method overrides the decode method from the superclass and populates
+  /// the various component maps of the APIComponents object. It decodes each
+  /// component type (schemas, responses, parameters, etc.) from the provided
+  /// KeyedArchive object.
+  ///
+  /// The method uses removeNullsFromMap to ensure that no null values are
+  /// present in the decoded maps. Each component type is decoded using a
+  /// specific factory function to create new instances of the appropriate type.
+  ///
+  /// Note: The 'examples' and 'links' components are currently commented out
+  /// and not being decoded.
+  ///
+  /// Parameters:
+  ///   object: A KeyedArchive containing the encoded APIComponents data.
   @override
   void decode(KeyedArchive object) {
     super.decode(object);
@@ -136,6 +204,22 @@ class APIComponents extends APIObject {
     );
   }
 
+  /// Encodes the APIComponents object into a KeyedArchive.
+  ///
+  /// This method overrides the encode method from the superclass and serializes
+  /// the various component maps of the APIComponents object. It encodes each
+  /// non-empty component type (schemas, responses, parameters, etc.) into the
+  /// provided KeyedArchive object.
+  ///
+  /// The method only encodes non-empty maps to avoid creating unnecessary empty
+  /// objects in the resulting OpenAPI specification. Each component type is
+  /// encoded using the encodeObjectMap method of the KeyedArchive.
+  ///
+  /// Note: The 'examples' and 'links' components are currently commented out
+  /// and not being encoded.
+  ///
+  /// Parameters:
+  ///   object: A KeyedArchive to which the APIComponents data will be encoded.
   @override
   void encode(KeyedArchive object) {
     super.encode(object);

packages/openapi/lib/src/v3/document.dart

@@ -11,17 +11,56 @@ import 'package:protevus_typeforge/codable.dart';
 import 'package:protevus_openapi/object.dart';
 import 'package:protevus_openapi/v3.dart';
 
-/// This is the root document object of the OpenAPI document.
+/// This class represents the root document object of the OpenAPI document.
+///
+/// It contains all the necessary fields to describe an API according to the OpenAPI Specification.
+/// The class provides methods to create an empty specification, create from a map,
+/// encode to and decode from a KeyedArchive, and convert to a map.
+///
+/// Required fields:
+/// - version: The semantic version number of the OpenAPI Specification.
+/// - info: Metadata about the API.
+/// - paths: Available paths and operations for the API.
+///
+/// Optional fields:
+/// - servers: Connectivity information to target servers.
+/// - components: Reusable schemas for the specification.
+/// - security: Declaration of security mechanisms that can be used across the API.
+/// - tags: List of tags used by the specification with additional metadata.
+///
+/// This class extends APIObject and implements encoding and decoding logic
+/// to work with the KeyedArchive serialization system.
 class APIDocument extends APIObject {
-  /// Creates an empty specification.
+  /// Creates an empty APIDocument instance.
+  ///
+  /// This constructor initializes a new APIDocument with default values for all fields.
+  /// It can be used as a starting point for building a new OpenAPI specification document.
   APIDocument();
 
-  /// Creates a specification from decoded JSON or YAML document object.
+  /// Creates an APIDocument instance from a decoded JSON or YAML document object.
+  ///
+  /// This constructor initializes a new APIDocument by decoding the provided [map].
+  /// The [map] should contain key-value pairs representing the structure of an OpenAPI document.
+  ///
+  /// It uses [KeyedArchive.unarchive] to convert the map into a KeyedArchive object,
+  /// which is then decoded to populate the fields of the APIDocument.
+  ///
+  /// The [allowReferences] parameter is set to true, allowing the decoding process
+  /// to handle references within the document.
+  ///
+  /// Example:
+  /// ```dart
+  /// var document = APIDocument.fromMap({
+  ///   'openapi': '3.0.0',
+  ///   'info': {'title': 'Sample API', 'version': '1.0.0'},
+  ///   'paths': {}
+  /// });
+  /// ```
   APIDocument.fromMap(Map<String, dynamic> map) {
     decode(KeyedArchive.unarchive(map, allowReferences: true));
   }
 
-  /// This string MUST be the semantic version number of the OpenAPI Specification version that the OpenAPI document uses.
+  /// The semantic version number of the OpenAPI Specification that this document uses.
   ///
   /// REQUIRED. The openapi field SHOULD be used by tooling specifications and clients to interpret the OpenAPI document. This is not related to the API info.version string.
   String version = "3.0.0";
@@ -29,35 +68,144 @@ class APIDocument extends APIObject {
   /// Provides metadata about the API.
   ///
   /// REQUIRED. The metadata MAY be used by tooling as required.
+  ///
+  /// This field is of type [APIInfo] and is initialized with an empty instance
+  /// using [APIInfo.empty()]. It contains essential information about the API,
+  /// such as its title, version, description, and other relevant metadata.
+  /// This information is crucial for API documentation and client generation tools.
   APIInfo info = APIInfo.empty();
 
-  /// An array of [APIServerDescription], which provide connectivity information to a target server.
+  /// An array of [APIServerDescription] objects that provide connectivity information to target servers.
   ///
   /// If the servers property is not provided, or is an empty array, the default value would be a [APIServerDescription] with a url value of /.
   List<APIServerDescription?>? servers;
 
   /// The available paths and operations for the API.
   ///
-  /// REQUIRED.
+  /// REQUIRED. This field is a map where each key represents a unique path in the API,
+  /// and the corresponding value is an [APIPath] object describing the operations
+  /// available on that path.
+  ///
+  /// The paths field is a crucial part of the OpenAPI specification as it defines
+  /// the structure and endpoints of the API. Each path may support multiple HTTP
+  /// methods (GET, POST, PUT, DELETE, etc.), each with its own operation details.
+  ///
+  /// Example:
+  /// ```dart
+  /// {
+  ///   "/users": APIPath(...),
+  ///   "/products": APIPath(...),
+  /// }
+  /// ```
+  ///
+  /// Note: This field is nullable, but it's required for a valid OpenAPI document.
+  /// An empty map should be used instead of null for APIs with no paths.
   Map<String, APIPath?>? paths;
 
   /// An element to hold various schemas for the specification.
+  ///
+  /// This field allows the definition of various reusable objects for different aspects of the OAS.
+  /// It can include schemas, responses, parameters, examples, and more.
+  /// These components can be referenced throughout the specification, promoting reusability and reducing duplication.
+  /// The field is optional but can significantly improve the organization and maintainability of large API specifications.
+  ///
+  /// Example usage:
+  /// ```dart
+  /// components = APIComponents()
+  ///   ..schemas = {'User': APISchemaObject()}
+  ///   ..responses = {'NotFound': APIResponse()};
+  /// ```
   APIComponents? components;
 
   /// A declaration of which security mechanisms can be used across the API.
   ///
-  /// The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. Individual operations can override this definition.
+  /// This field is an optional list of [APISecurityRequirement] objects that define
+  /// the security schemes applicable to the entire API. Each object in the list
+  /// represents an alternative set of security requirements.
+  ///
+  /// Key features:
+  /// - Multiple security requirement objects can be specified.
+  /// - Only one of the security requirement objects needs to be satisfied to authorize a request.
+  /// - Individual operations can override this global definition.
+  /// - If the list is empty, it means that there are no global security requirements.
+  ///
+  /// The security schemes referenced in this list must be defined in the
+  /// [components.securitySchemes] section of the OpenAPI document.
+  ///
+  /// Example usage:
+  /// ```dart
+  /// security = [
+  ///   APISecurityRequirement()..addRequirement("api_key", []),
+  ///   APISecurityRequirement()
+  ///     ..addRequirement("oauth2", ["read:api"])
+  ///     ..addRequirement("userPassword", []),
+  /// ];
+  /// ```
+  ///
+  /// In this example, a request can be authorized using either an API key,
+  /// or a combination of OAuth2 with "read:api" scope and user password.
   List<APISecurityRequirement?>? security;
 
   /// A list of tags used by the specification with additional metadata.
   ///
-  /// The order of the tags can be used to reflect on their order by the parsing tools. Not all tags that are used by the Operation Object must be declared. The tags that are not declared MAY be organized randomly or based on the tools' logic. Each tag name in the list MUST be unique.
+  /// The order of the tags can be used to reflect on their order by the parsing tools.
+  /// Not all tags that are used by the Operation Object must be declared.
+  /// The tags that are not declared MAY be organized randomly or based on the tools' logic.
+  /// Each tag name in the list MUST be unique.
+  ///
+  /// This field is optional and can be null. When provided, it contains a list of [APITag] objects.
+  /// Each [APITag] typically includes a name and description, and can be used to categorize and
+  /// group related operations across the API.
+  ///
+  /// Tags defined here can be referenced by [APIOperation] objects throughout the specification,
+  /// allowing for logical grouping and organization of API endpoints.
+  ///
+  /// Example usage:
+  /// ```dart
+  /// tags = [
+  ///   APITag()
+  ///     ..name = "users"
+  ///     ..description = "Operations about users",
+  ///   APITag()
+  ///     ..name = "products"
+  ///     ..description = "Product-related operations",
+  /// ];
+  /// ```
+  ///
+  /// Note: While this field is optional, using tags can significantly improve the structure
+  /// and readability of API documentation generated from the OpenAPI specification.
   List<APITag?>? tags;
 
+  /// Converts this APIDocument instance to a Map<String, dynamic>.
+  ///
+  /// This method uses KeyedArchive.archive to serialize the APIDocument object
+  /// into a Map representation. The resulting map can be used for JSON/YAML
+  /// serialization or other purposes where a dictionary-like structure is needed.
+  ///
+  /// The allowReferences parameter is set to true, which means that object
+  /// references within the document will be preserved during the archiving process.
+  ///
+  /// Returns:
+  ///   A Map<String, dynamic> representation of this APIDocument instance.
   Map<String, dynamic> asMap() {
     return KeyedArchive.archive(this, allowReferences: true);
   }
 
+  /// Decodes the APIDocument from a KeyedArchive object.
+  ///
+  /// This method populates the fields of the APIDocument instance using data
+  /// from the provided [object]. It decodes various components of the OpenAPI
+  /// specification, including version, info, servers, paths, components,
+  /// security requirements, and tags.
+  ///
+  /// The method uses default values or empty instances for optional fields
+  /// if they are not present in the archive.
+  ///
+  /// Parameters:
+  ///   - object: A KeyedArchive containing the encoded APIDocument data.
+  ///
+  /// Note: This method overrides the decode method from the superclass and
+  /// calls the superclass implementation before decoding specific fields.
   @override
   void decode(KeyedArchive object) {
     super.decode(object);
@@ -74,6 +222,23 @@ class APIDocument extends APIObject {
     tags = object.decodeObjects("tags", () => APITag.empty());
   }
 
+  /// Encodes the APIDocument into a KeyedArchive object.
+  ///
+  /// This method serializes the APIDocument instance into the provided [object],
+  /// which is a KeyedArchive. It encodes all the fields of the APIDocument,
+  /// including version, info, servers, paths, components, security, and tags.
+  ///
+  /// Before encoding, it checks if the required fields 'info' and 'paths' are valid.
+  /// If these are not valid or missing, it throws an ArgumentError.
+  ///
+  /// Parameters:
+  ///   - object: A KeyedArchive to encode the APIDocument data into.
+  ///
+  /// Throws:
+  ///   - ArgumentError: If 'info' is not valid or 'paths' is null.
+  ///
+  /// Note: This method overrides the encode method from the superclass and
+  /// calls the superclass implementation before encoding specific fields.
   @override
   void encode(KeyedArchive object) {
     super.encode(object);

packages/openapi/lib/src/v3/encoding.dart

@@ -12,7 +12,29 @@ import 'package:protevus_openapi/object.dart';
 import 'package:protevus_openapi/v3.dart';
 
 /// A single encoding definition applied to a single schema property.
+///
+/// This class represents an encoding definition as specified in the OpenAPI Specification.
+/// It provides details about how a specific property should be serialized when sent as
+/// part of a request body, particularly for multipart requests or application/x-www-form-urlencoded
+/// request bodies.
+///
+/// Properties:
+/// - [contentType]: Specifies the Content-Type for encoding a specific property.
+/// - [headers]: Additional headers that may be sent with the request.
+/// - [allowReserved]: Determines if reserved characters should be percent-encoded.
+/// - [explode]: Controls how arrays and objects are serialized.
+/// - [style]: Describes how a specific property value will be serialized.
+///
+/// This class extends [APIObject] and implements [Codable] for serialization and deserialization.
 class APIEncoding extends APIObject {
+  /// Creates a new [APIEncoding] instance.
+  ///
+  /// Parameters:
+  /// - [contentType]: The Content-Type for encoding a specific property.
+  /// - [headers]: A map of additional headers to be included with the request.
+  /// - [style]: Describes how a specific property value will be serialized.
+  /// - [allowReserved]: Determines if reserved characters should be percent-encoded. Defaults to false.
+  /// - [explode]: Controls how arrays and objects are serialized. Defaults to false.
   APIEncoding({
     this.contentType,
     this.headers,
@@ -21,35 +43,102 @@ class APIEncoding extends APIObject {
     this.explode = false,
   });
 
+  /// Creates an empty [APIEncoding] instance with default values.
+  ///
+  /// This constructor initializes an [APIEncoding] with [allowReserved] and [explode]
+  /// set to false. All other properties are left uninitialized.
   APIEncoding.empty()
       : allowReserved = false,
         explode = false;
 
   /// The Content-Type for encoding a specific property.
   ///
-  /// Default value depends on the property type: for string with format being binary – application/octet-stream; for other primitive types – text/plain; for object - application/json; for array – the default is defined based on the inner type. The value can be a specific media type (e.g. application/json), a wildcard media type (e.g. image/*), or a comma-separated list of the two types.
+  /// Specifies the media type to be used for encoding this property when sending the request body.
+  /// The default value depends on the property type:
+  /// - For string with format being binary: application/octet-stream
+  /// - For other primitive types: text/plain
+  /// - For object: application/json
+  /// - For array: defined based on the inner type
+  ///
+  /// The value can be:
+  /// - A specific media type (e.g., application/json)
+  /// - A wildcard media type (e.g., image/*)
+  /// - A comma-separated list of the above types
+  ///
+  /// This property is particularly relevant for multipart request bodies and
+  /// application/x-www-form-urlencoded request bodies.
   String? contentType;
 
   /// A map allowing additional information to be provided as headers, for example Content-Disposition.
   ///
   /// Content-Type is described separately and SHALL be ignored in this section. This property SHALL be ignored if the request body media type is not a multipart.
+  ///
+  /// This map represents a collection of headers associated with the encoding. Each key in the map
+  /// is a header name, and the corresponding value is an [APIHeader] object that defines the header's
+  /// properties. These headers provide supplementary information for the encoded content.
+  ///
+  /// Note:
+  /// - The Content-Type header is handled separately and should not be included in this map.
+  /// - This property is only applicable for multipart request body media types. It will be ignored
+  ///   for other media types.
+  ///
+  /// Example usage:
+  /// ```dart
+  /// headers = {
+  ///   "Content-Disposition": APIHeader(description: "Specifies the filename for the uploaded file"),
+  ///   "X-Custom-Header": APIHeader(description: "A custom header for additional metadata")
+  /// };
+  /// ```
   Map<String, APIHeader?>? headers;
 
-  /// Determines whether the parameter value SHOULD allow reserved characters, as defined by RFC3986 :/?#[]@!$&'()*+,;= to be included without percent-encoding.
+  /// Determines whether the parameter value should allow reserved characters without percent-encoding.
   ///
   /// The default value is false. This property SHALL be ignored if the request body media type is not application/x-www-form-urlencoded.
   bool? allowReserved;
 
-  /// When this is true, property values of type array or object generate separate parameters for each value of the array, or key-value-pair of the map.
+  /// Determines how array and object properties are serialized in form-style parameters.
   ///
   /// For other types of properties this property has no effect. When style is form, the default value is true. For all other styles, the default value is false. This property SHALL be ignored if the request body media type is not application/x-www-form-urlencoded.
   bool? explode;
 
   /// Describes how a specific property value will be serialized depending on its type.
   ///
-  /// See [APIParameter] for details on the style property. The behavior follows the same values as query parameters, including default values. This property SHALL be ignored if the request body media type is not application/x-www-form-urlencoded.
+  /// This property specifies the serialization style for the encoded value. It follows the same
+  /// behavior and values as the style property for query parameters in [APIParameter].
+  ///
+  /// The style affects how the property is serialized, especially for complex types like arrays
+  /// and objects. Common values include:
+  /// - 'form': comma-separated values for arrays (default for application/x-www-form-urlencoded)
+  /// - 'spaceDelimited': space-separated values for arrays
+  /// - 'pipeDelimited': pipe-separated values for arrays
+  /// - 'deepObject': for nested objects
+  ///
+  /// Note:
+  /// - This property is only applicable when the request body media type is
+  ///   application/x-www-form-urlencoded. It will be ignored for other media types.
+  /// - If not specified, the default style depends on the parameter type and the media type
+  ///   of the request body.
+  ///
+  /// See [APIParameter] for more detailed information on style values and their effects.
   String? style;
 
+  /// Decodes the [APIEncoding] object from a [KeyedArchive].
+  ///
+  /// This method is responsible for populating the properties of the [APIEncoding]
+  /// instance from the provided [KeyedArchive] object. It decodes each property
+  /// using the appropriate key and method from the archive.
+  ///
+  /// The following properties are decoded:
+  /// - [contentType]: The Content-Type for encoding a specific property.
+  /// - [headers]: A map of additional headers to be included with the request.
+  /// - [allowReserved]: Determines if reserved characters should be percent-encoded.
+  /// - [explode]: Controls how arrays and objects are serialized.
+  /// - [style]: Describes how a specific property value will be serialized.
+  ///
+  /// This method also calls the superclass's decode method to handle any inherited properties.
+  ///
+  /// Parameters:
+  /// - [object]: The [KeyedArchive] containing the encoded data for this [APIEncoding] instance.
   @override
   void decode(KeyedArchive object) {
     super.decode(object);
@@ -61,6 +150,23 @@ class APIEncoding extends APIObject {
     style = object.decode("style");
   }
 
+  /// Encodes the [APIEncoding] object into a [KeyedArchive].
+  ///
+  /// This method is responsible for serializing the properties of the [APIEncoding]
+  /// instance into the provided [KeyedArchive] object. It encodes each property
+  /// using the appropriate key and method for the archive.
+  ///
+  /// The following properties are encoded:
+  /// - [contentType]: The Content-Type for encoding a specific property.
+  /// - [headers]: A map of additional headers to be included with the request.
+  /// - [allowReserved]: Determines if reserved characters should be percent-encoded.
+  /// - [explode]: Controls how arrays and objects are serialized.
+  /// - [style]: Describes how a specific property value will be serialized.
+  ///
+  /// This method also calls the superclass's encode method to handle any inherited properties.
+  ///
+  /// Parameters:
+  /// - [object]: The [KeyedArchive] where the encoded data for this [APIEncoding] instance will be stored.
   @override
   void encode(KeyedArchive object) {
     super.encode(object);

packages/openapi/lib/src/v3/header.dart

@@ -10,15 +10,43 @@
 import 'package:protevus_typeforge/codable.dart';
 import 'package:protevus_openapi/v3.dart';
 
-/// [APIHeader] follows the structure of the [APIParameter] with the following changes:
+/// Represents an API Header in OpenAPI specifications.
 ///
 /// name MUST NOT be specified, it is given in the corresponding headers map.
 /// in MUST NOT be specified, it is implicitly in header.
 /// All traits that are affected by the location MUST be applicable to a location of header (for example, style).
 class APIHeader extends APIParameter {
+  /// Creates an [APIHeader] instance.
+  ///
+  /// This constructor initializes an [APIHeader] with an optional [schema].
+  /// The [schema] parameter is of type [APISchemaObject] and defines the
+  /// structure and constraints of the header value.
+  ///
+  /// The constructor calls the superclass constructor [super.header] with
+  /// a null name and the provided schema.
   APIHeader({APISchemaObject? schema}) : super.header(null, schema: schema);
+
+  /// Creates an empty [APIHeader] instance.
+  ///
+  /// This constructor initializes an [APIHeader] without specifying a schema.
+  /// It calls the superclass constructor [super.header] with a null name and
+  /// no schema, resulting in an empty header definition.
   APIHeader.empty() : super.header(null);
 
+  /// Encodes the [APIHeader] object into a [KeyedArchive].
+  ///
+  /// This method overrides the superclass's encode method to handle the specific
+  /// encoding requirements of an API header. It performs the following steps:
+  /// 1. Temporarily sets the 'name' property to "temporary".
+  /// 2. Calls the superclass's encode method to perform the base encoding.
+  /// 3. Removes the "name" and "in" keys from the encoded object, as these
+  ///    are not required for API headers in OpenAPI specifications.
+  /// 4. Resets the 'name' property to null.
+  ///
+  /// This approach ensures that the header is correctly encoded while adhering
+  /// to OpenAPI specifications for headers.
+  ///
+  /// [object] The [KeyedArchive] to encode the header information into.
   @override
   void encode(KeyedArchive object) {
     name = "temporary";

packages/openapi/lib/src/v3/media_type.dart

@@ -11,19 +11,72 @@ import 'package:protevus_typeforge/codable.dart';
 import 'package:protevus_openapi/object.dart';
 import 'package:protevus_openapi/v3.dart';
 
+/// Represents a media type in an API specification.
+///
+/// An [APIMediaType] object provides schema and encoding information for a specific media type.
+/// It is typically used in OpenAPI specifications to describe the structure and format of request
+/// or response bodies for different content types.
+///
+/// The [schema] property defines the structure of the media type content, while the [encoding]
+/// property provides additional information about how to encode specific properties, particularly
+/// useful for multipart and application/x-www-form-urlencoded media types.
+///
+/// This class extends [APIObject] and implements [Codable] for serialization and deserialization.
+/// The [decode] and [encode] methods are overridden to handle the specific properties of this class.
 /// Each [APIMediaType] provides schema and examples for the media type identified by its key.
 class APIMediaType extends APIObject {
+  /// Creates an [APIMediaType] instance.
+  ///
+  /// [schema] is an optional [APISchemaObject] that defines the structure of the media type content.
+  /// [encoding] is an optional [Map] that provides additional information about how to encode specific properties.
+  ///
+  /// This constructor allows for the creation of an [APIMediaType] with or without a schema and encoding information.
   APIMediaType({this.schema, this.encoding});
+
+  /// Creates an empty [APIMediaType] instance.
+  ///
+  /// This constructor initializes an [APIMediaType] with no schema or encoding information.
+  /// It can be used when you need to create a placeholder or default media type object
+  /// that will be populated later.
   APIMediaType.empty();
 
   /// The schema defining the type used for the request body.
+  ///
+  /// This property holds an optional [APISchemaObject] that describes the structure
+  /// and constraints of the data for this media type. It defines the expected format,
+  /// types, and validation rules for the request body when this media type is used.
+  /// If not specified, it indicates that the structure of the request body is not strictly defined
+  /// or is described elsewhere in the API specification.
   APISchemaObject? schema;
 
   /// A map between a property name and its encoding information.
   ///
-  /// The key, being the property name, MUST exist in the schema as a property. The encoding object SHALL only apply to requestBody objects when the media type is multipart or application/x-www-form-urlencoded.
+  /// This property holds an optional [Map] where each key is a property name and each value
+  /// is an [APIEncoding] object providing encoding information for that property.
+  ///
+  /// The key, being the property name, MUST exist in the schema as a property. The encoding
+  /// object SHALL only apply to requestBody objects when the media type is multipart or
+  /// application/x-www-form-urlencoded.
+  ///
+  /// This map is particularly useful for specifying additional metadata about the encoding
+  /// of specific properties within the media type, such as content type, headers, or style
+  /// when dealing with complex data structures in request bodies.
+  ///
+  /// If this property is null or empty, it indicates that no specific encoding information
+  /// is provided for the properties of this media type.
   Map<String, APIEncoding?>? encoding;
 
+  /// Decodes the [APIMediaType] object from a [KeyedArchive].
+  ///
+  /// This method overrides the [decode] method from the superclass and is responsible for
+  /// populating the properties of the [APIMediaType] object from the given [KeyedArchive].
+  ///
+  /// It performs the following operations:
+  /// 1. Calls the superclass's decode method to handle any inherited properties.
+  /// 2. Decodes the "schema" field into an [APISchemaObject], if present.
+  /// 3. Decodes the "encoding" field into a Map of [String] to [APIEncoding], if present.
+  ///
+  /// [object] is the [KeyedArchive] containing the encoded data for this [APIMediaType].
   @override
   void decode(KeyedArchive object) {
     super.decode(object);
@@ -32,6 +85,17 @@ class APIMediaType extends APIObject {
     encoding = object.decodeObjectMap("encoding", () => APIEncoding());
   }
 
+  /// Encodes the [APIMediaType] object into a [KeyedArchive].
+  ///
+  /// This method overrides the [encode] method from the superclass and is responsible for
+  /// serializing the properties of the [APIMediaType] object into the given [KeyedArchive].
+  ///
+  /// It performs the following operations:
+  /// 1. Calls the superclass's encode method to handle any inherited properties.
+  /// 2. Encodes the "schema" field from the [APISchemaObject], if present.
+  /// 3. Encodes the "encoding" field as a Map of [String] to [APIEncoding], if present.
+  ///
+  /// [object] is the [KeyedArchive] where the encoded data for this [APIMediaType] will be stored.
   @override
   void encode(KeyedArchive object) {
     super.encode(object);

packages/openapi/lib/src/v3/metadata.dart

@@ -14,8 +14,47 @@ import 'package:protevus_openapi/v3.dart';
 /// The object provides metadata about the API.
 ///
 /// The metadata MAY be used by the clients if needed, and MAY be presented in editing or documentation generation tools for convenience.
+///
+/// This class represents the OpenAPI Info Object, which contains basic information about the API.
+/// It includes required fields like 'title' and 'version', as well as optional fields such as
+/// 'description', 'termsOfServiceURL', 'contact', and 'license'.
+///
+/// The [APIInfo] class provides methods to encode and decode the information to and from a [KeyedArchive],
+/// which is useful for serialization and deserialization of the API metadata.
+///
+/// Usage:
+/// ```dart
+/// var info = APIInfo('My API', '1.0.0',
+///   description: 'This is a sample API',
+///   termsOfServiceURL: Uri.parse('https://example.com/terms'),
+///   contact: APIContact(name: 'API Support', email: 'support@example.com'),
+///   license: APILicense('Apache 2.0', url: Uri.parse('https://www.apache.org/licenses/LICENSE-2.0.html'))
+/// );
+/// ```
+///
+/// The [isValid] getter can be used to check if the required fields are non-null.
 class APIInfo extends APIObject {
-  /// Creates empty metadata for specification.
+  /// Creates an [APIInfo] instance with the required fields and optional metadata.
+  ///
+  /// [title] and [version] are required parameters.
+  ///
+  /// Optional parameters include:
+  /// - [description]: A short description of the API.
+  /// - [termsOfServiceURL]: A URL to the Terms of Service for the API.
+  /// - [license]: The license information for the exposed API.
+  /// - [contact]: The contact information for the exposed API.
+  ///
+  /// Example:
+  /// ```dart
+  /// var info = APIInfo(
+  ///   'My API',
+  ///   '1.0.0',
+  ///   description: 'This is a sample API',
+  ///   termsOfServiceURL: Uri.parse('https://example.com/terms'),
+  ///   license: APILicense('Apache 2.0'),
+  ///   contact: APIContact(name: 'API Support', email: 'support@example.com')
+  /// );
+  /// ```
   APIInfo(
     this.title,
     this.version, {
@@ -25,36 +64,143 @@ class APIInfo extends APIObject {
     this.contact,
   });
 
+  /// Creates an empty [APIInfo] instance.
+  ///
+  /// This constructor initializes an [APIInfo] object without setting any of its properties.
+  /// It can be useful when you need to create an instance of [APIInfo] and populate its
+  /// properties later, or when decoding from a serialized format.
   APIInfo.empty();
 
   /// The title of the application.
   ///
-  /// REQUIRED.
+  /// This field is REQUIRED according to the OpenAPI Specification.
+  /// It provides the name of the API or application that this [APIInfo] object describes.
+  ///
+  /// Example:
+  /// ```dart
+  /// var info = APIInfo('My Amazing API', '1.0.0');
+  /// print(info.title); // Output: My Amazing API
+  /// ```
+  ///
+  /// Note: Despite being marked as required in the specification, this field is nullable
+  /// to allow for deserialization of incomplete data. Always ensure this field is set
+  /// before using the [APIInfo] object in production.
   String? title;
 
   /// A short description of the application.
   ///
-  /// CommonMark syntax MAY be used for rich text representation.
+  /// This field provides a brief summary of the API or application that this [APIInfo] object describes.
+  /// It's an optional field that can be used to give users a quick understanding of the API's purpose.
+  ///
+  /// The OpenAPI Specification allows for CommonMark syntax to be used in this field,
+  /// enabling rich text representation for more detailed or formatted descriptions.
+  ///
+  /// Example:
+  /// ```dart
+  /// var info = APIInfo('My API', '1.0.0',
+  ///   description: 'This API provides access to our product catalog and order management system.'
+  /// );
+  /// ```
+  ///
+  /// Note: This field is nullable, as it's not a required field in the OpenAPI Specification.
   String? description;
 
-  /// The version of the OpenAPI document (which is distinct from the OpenAPI Specification version or the API implementation version).
+  /// The version of the OpenAPI document.
   ///
   /// REQUIRED.
   String? version;
 
   /// A URL to the Terms of Service for the API.
   ///
-  /// MUST be in the format of a URL.
+  /// This field provides a link to the Terms of Service for the API, if available.
+  /// It must be in the format of a valid URL.
+  ///
+  /// According to the OpenAPI Specification, if provided, this field MUST be a URL.
+  /// It's an optional field, so it can be null if no Terms of Service URL is specified.
+  ///
+  /// Example:
+  /// ```dart
+  /// var info = APIInfo('My API', '1.0.0',
+  ///   termsOfServiceURL: Uri.parse('https://example.com/terms')
+  /// );
+  /// ```
+  ///
+  /// Note: When setting this field, ensure that the provided URI is valid and accessible.
   Uri? termsOfServiceURL;
 
   /// The contact information for the exposed API.
+  ///
+  /// This field contains an [APIContact] object that provides contact information
+  /// for the API. It can include details such as the name of the contact person or
+  /// organization, a URL for contact information, and an email address.
+  ///
+  /// This field is optional according to the OpenAPI Specification, so it can be null
+  /// if no contact information is provided.
+  ///
+  /// Example:
+  /// ```dart
+  /// var info = APIInfo('My API', '1.0.0',
+  ///   contact: APIContact(
+  ///     name: 'API Support',
+  ///     url: Uri.parse('https://www.example.com/support'),
+  ///     email: 'support@example.com'
+  ///   )
+  /// );
+  /// ```
   APIContact? contact;
 
   /// The license information for the exposed API.
+  ///
+  /// This field contains an [APILicense] object that provides license information
+  /// for the API. It typically includes the name of the license and optionally
+  /// a URL where the full license text can be found.
+  ///
+  /// This field is optional according to the OpenAPI Specification, so it can be null
+  /// if no license information is provided.
+  ///
+  /// Example:
+  /// ```dart
+  /// var info = APIInfo('My API', '1.0.0',
+  ///   license: APILicense('Apache 2.0', url: Uri.parse('https://www.apache.org/licenses/LICENSE-2.0.html'))
+  /// );
+  /// ```
   APILicense? license;
 
+  /// Checks if the [APIInfo] object is valid according to the OpenAPI Specification.
+  ///
+  /// This getter returns `true` if both the [title] and [version] fields are non-null,
+  /// as these are required fields in the OpenAPI Specification for the Info Object.
+  ///
+  /// Returns:
+  ///   A boolean value: `true` if both [title] and [version] are non-null, `false` otherwise.
+  ///
+  /// Example:
+  /// ```dart
+  /// var info = APIInfo('My API', '1.0.0');
+  /// print(info.isValid); // Output: true
+  ///
+  /// var incompleteInfo = APIInfo.empty();
+  /// print(incompleteInfo.isValid); // Output: false
+  /// ```
   bool get isValid => title != null && version != null;
 
+  /// Decodes the [APIInfo] object from a [KeyedArchive].
+  ///
+  /// This method is responsible for populating the properties of the [APIInfo] object
+  /// from a [KeyedArchive]. It decodes the following fields:
+  /// - 'title': The title of the API (String)
+  /// - 'description': A short description of the API (String)
+  /// - 'termsOfService': URL to the Terms of Service (Uri)
+  /// - 'contact': Contact information (APIContact)
+  /// - 'license': License information (APILicense)
+  /// - 'version': The version of the API (String)
+  ///
+  /// The 'contact' and 'license' fields are decoded as objects of their respective types.
+  ///
+  /// This method overrides the [decode] method from the superclass and calls it before
+  /// performing its own decoding operations.
+  ///
+  /// @param object The [KeyedArchive] containing the encoded [APIInfo] data.
   @override
   void decode(KeyedArchive object) {
     super.decode(object);
@@ -67,6 +213,25 @@ class APIInfo extends APIObject {
     version = object.decode("version");
   }
 
+  /// Encodes the [APIInfo] object into a [KeyedArchive].
+  ///
+  /// This method is responsible for serializing the properties of the [APIInfo] object
+  /// into a [KeyedArchive]. It encodes the following fields:
+  /// - 'title': The title of the API (String)
+  /// - 'description': A short description of the API (String)
+  /// - 'version': The version of the API (String)
+  /// - 'termsOfService': URL to the Terms of Service (Uri)
+  /// - 'contact': Contact information (APIContact)
+  /// - 'license': License information (APILicense)
+  ///
+  /// The method first checks if the required fields 'title' and 'version' are non-null.
+  /// If either is null, it throws an [ArgumentError].
+  ///
+  /// This method overrides the [encode] method from the superclass and calls it before
+  /// performing its own encoding operations.
+  ///
+  /// @param object The [KeyedArchive] to encode the [APIInfo] data into.
+  /// @throws ArgumentError if 'title' or 'version' is null.
   @override
   void encode(KeyedArchive object) {
     super.encode(object);
@@ -87,23 +252,112 @@ class APIInfo extends APIObject {
 }
 
 /// Contact information for the exposed API.
+///
+/// This class represents the Contact Object as defined in the OpenAPI Specification.
+/// It provides optional fields for the name, URL, and email of the contact person or organization
+/// responsible for the API.
+///
+/// The [APIContact] class extends [APIObject] and provides methods to encode and decode
+/// the contact information to and from a [KeyedArchive], which is useful for serialization
+/// and deserialization of the API metadata.
+///
+/// Usage:
+/// ```dart
+/// var contact = APIContact(
+///   name: 'API Support',
+///   url: Uri.parse('https://www.example.com/support'),
+///   email: 'support@example.com'
+/// );
+/// ```
 class APIContact extends APIObject {
+  /// Creates an [APIContact] instance with optional name, URL, and email.
+  ///
+  /// This constructor allows you to create an [APIContact] object by providing
+  /// optional parameters for the contact's name, URL, and email address.
+  ///
+  /// Parameters:
+  /// - [name]: The identifying name of the contact person/organization.
+  /// - [url]: The URL pointing to the contact information. Must be a valid URI.
+  /// - [email]: The email address of the contact person/organization.
+  ///
+  /// Example:
+  /// ```dart
+  /// var contact = APIContact(
+  ///   name: 'API Support',
+  ///   url: Uri.parse('https://www.example.com/support'),
+  ///   email: 'support@example.com'
+  /// );
+  /// ```
   APIContact({this.name, this.url, this.email});
+
+  /// Creates an empty [APIContact] instance.
+  ///
+  /// This constructor initializes an [APIContact] object without setting any of its properties.
+  /// It can be useful when you need to create an instance of [APIContact] and populate its
+  /// properties later, or when decoding from a serialized format.
   APIContact.empty();
 
   /// The identifying name of the contact person/organization.
+  ///
+  /// This property represents the name of the individual or organization
+  /// responsible for the API. It's an optional field in the OpenAPI Specification,
+  /// so it can be null if no contact name is provided.
+  ///
+  /// Example:
+  /// ```dart
+  /// var contact = APIContact(name: 'API Support Team');
+  /// ```
   String? name;
 
   /// The URL pointing to the contact information.
   ///
-  /// MUST be in the format of a URL.
+  /// This property represents a URL that provides additional contact information
+  /// for the API. According to the OpenAPI Specification, if provided, this field
+  /// MUST be in the format of a valid URL.
+  ///
+  /// This field is optional and can be null if no contact URL is specified.
+  ///
+  /// Example:
+  /// ```dart
+  /// var contact = APIContact(
+  ///   url: Uri.parse('https://www.example.com/api-support')
+  /// );
+  /// ```
+  ///
+  /// Note: When setting this field, ensure that the provided URI is valid and accessible.
   Uri? url;
 
   /// The email address of the contact person/organization.
   ///
+  /// This property represents the email address for contacting the individual or organization
+  /// responsible for the API. According to the OpenAPI Specification, if provided, this field
+  /// MUST be in the format of a valid email address.
+  ///
+  /// This field is optional and can be null if no contact email is specified.
+  ///
+  /// Example:
+  /// ```dart
+  /// var contact = APIContact(email: 'support@example.com');
+  /// ```
+  ///
+  /// Note: When setting this field, ensure that the provided email address is valid and follows
+  /// the standard email format (e.g., username@domain.com).
+  ///
   /// MUST be in the format of an email address.
   String? email;
 
+  /// Decodes the [APIContact] object from a [KeyedArchive].
+  ///
+  /// This method is responsible for populating the properties of the [APIContact] object
+  /// from a [KeyedArchive]. It decodes the following fields:
+  /// - 'name': The identifying name of the contact person/organization (String)
+  /// - 'url': The URL pointing to the contact information (Uri)
+  /// - 'email': The email address of the contact person/organization (String)
+  ///
+  /// This method overrides the [decode] method from the superclass and calls it before
+  /// performing its own decoding operations.
+  ///
+  /// @param object The [KeyedArchive] containing the encoded [APIContact] data.
   @override
   void decode(KeyedArchive object) {
     super.decode(object);
@@ -113,6 +367,18 @@ class APIContact extends APIObject {
     email = object.decode("email");
   }
 
+  /// Encodes the [APIContact] object into a [KeyedArchive].
+  ///
+  /// This method is responsible for serializing the properties of the [APIContact] object
+  /// into a [KeyedArchive]. It encodes the following fields:
+  /// - 'name': The identifying name of the contact person/organization (String)
+  /// - 'url': The URL pointing to the contact information (Uri)
+  /// - 'email': The email address of the contact person/organization (String)
+  ///
+  /// This method overrides the [encode] method from the superclass and calls it before
+  /// performing its own encoding operations.
+  ///
+  /// @param object The [KeyedArchive] to encode the [APIContact] data into.
   @override
   void encode(KeyedArchive object) {
     super.encode(object);
@@ -124,20 +390,90 @@ class APIContact extends APIObject {
 }
 
 /// License information for the exposed API.
+///
+/// This class represents the License Object as defined in the OpenAPI Specification.
+/// It provides information about the license under which the API is made available.
+///
+/// The [APILicense] class extends [APIObject] and provides methods to encode and decode
+/// the license information to and from a [KeyedArchive], which is useful for serialization
+/// and deserialization of the API metadata.
+///
+/// Usage:
+/// ```dart
+/// var license = APILicense('Apache 2.0', url: Uri.parse('https://www.apache.org/licenses/LICENSE-2.0.html'));
+/// ```
 class APILicense extends APIObject {
+  /// Creates an [APILicense] instance with a required name and an optional URL.
+  ///
+  /// This constructor initializes an [APILicense] object with the provided license name
+  /// and an optional URL to the full license text.
+  ///
+  /// Parameters:
+  /// - [name]: The name of the license. This parameter is required.
+  /// - [url]: An optional URL pointing to the full text of the license.
+  ///
+  /// Example:
+  /// ```dart
+  /// var license = APILicense('Apache 2.0', url: Uri.parse('https://www.apache.org/licenses/LICENSE-2.0.html'));
+  /// ```
   APILicense(this.name, {this.url});
+
+  /// Creates an empty [APILicense] instance.
+  ///
+  /// This constructor initializes an [APILicense] object without setting any of its properties.
+  /// It can be useful when you need to create an instance of [APILicense] and populate its
+  /// properties later, or when decoding from a serialized format.
   APILicense.empty();
 
   /// The license name used for the API.
   ///
+  /// This property represents the name of the license under which the API is made available.
+  /// According to the OpenAPI Specification, this field is REQUIRED for the License Object.
+  ///
+  /// Despite being marked as required in the specification, this field is nullable
+  /// to allow for deserialization of incomplete data. Always ensure this field is set
+  /// before using the [APILicense] object in production.
+  ///
+  /// Example:
+  /// ```dart
+  /// var license = APILicense('Apache 2.0');
+  /// print(license.name); // Output: Apache 2.0
+  /// ```
+  ///
   /// REQUIRED.
   String? name;
 
   /// A URL to the license used for the API.
   ///
+  /// This property represents a URL pointing to the full text of the license
+  /// under which the API is made available. According to the OpenAPI Specification,
+  /// if provided, this field MUST be in the format of a valid URL.
+  ///
+  /// This field is optional and can be null if no license URL is specified.
+  ///
+  /// Example:
+  /// ```dart
+  /// var license = APILicense('Apache 2.0',
+  ///   url: Uri.parse('https://www.apache.org/licenses/LICENSE-2.0.html')
+  /// );
+  /// ```
+  ///
+  /// Note: When setting this field, ensure that the provided URI is valid and accessible.
+  ///
   /// MUST be in the format of a URL.
   Uri? url;
 
+  /// Decodes the [APILicense] object from a [KeyedArchive].
+  ///
+  /// This method is responsible for populating the properties of the [APILicense] object
+  /// from a [KeyedArchive]. It decodes the following fields:
+  /// - 'name': The name of the license used for the API (String)
+  /// - 'url': A URL to the license used for the API (Uri)
+  ///
+  /// This method overrides the [decode] method from the superclass and calls it before
+  /// performing its own decoding operations.
+  ///
+  /// @param object The [KeyedArchive] containing the encoded [APILicense] data.
   @override
   void decode(KeyedArchive object) {
     super.decode(object);
@@ -146,6 +482,18 @@ class APILicense extends APIObject {
     url = object.decode("url");
   }
 
+  /// Encodes the [APILicense] object into a [KeyedArchive].
+  ///
+  /// This method is responsible for serializing the properties of the [APILicense] object
+  /// into a [KeyedArchive]. It encodes the following fields:
+  /// - 'name': The name of the license used for the API (String)
+  /// - 'url': A URL to the license used for the API (Uri)
+  ///
+  /// This method first calls the superclass's encode method, then checks if the required
+  /// 'name' field is non-null. If 'name' is null, it throws an [ArgumentError].
+  ///
+  /// @param object The [KeyedArchive] to encode the [APILicense] data into.
+  /// @throws ArgumentError if 'name' is null.
   @override
   void encode(KeyedArchive object) {
     super.encode(object);
@@ -162,21 +510,68 @@ class APILicense extends APIObject {
 /// Adds metadata to a single tag that is used by the [APIOperation].
 ///
 /// It is not mandatory to have a [APITag] per tag defined in the [APIOperation] instances.
+///
+/// The [APITag] class extends [APIObject] and provides methods to encode and decode
+/// the tag information to and from a [KeyedArchive], which is useful for serialization
+/// and deserialization of the API metadata.
+///
+/// Usage:
+/// ```dart
+/// var tag = APITag('user', description: 'User-related operations');
+/// ```
 class APITag extends APIObject {
+  /// Creates an [APITag] instance with a required name and an optional description.
+  ///
+  /// Parameters:
+  /// - [name]: The name of the tag. This parameter is required.
+  /// - [description]: An optional short description for the tag.
+  ///
+  /// Example:
+  /// ```dart
+  /// var tag = APITag('user', description: 'User-related operations');
+  /// ```
   APITag(this.name, {this.description});
 
+  /// Creates an empty [APITag] instance.
+  ///
+  /// This constructor initializes an [APITag] object without setting any of its properties.
+  /// It can be useful when you need to create an instance of [APITag] and populate its
+  /// properties later, or when decoding from a serialized format.
   APITag.empty();
 
   /// The name of the tag.
   ///
+  /// This property represents the name of the tag used to group operations.
+  /// According to the OpenAPI Specification, this field is REQUIRED for the Tag Object.
+  ///
+  /// Despite being marked as required in the specification, this field is nullable
+  /// to allow for deserialization of incomplete data. Always ensure this field is set
+  /// before using the [APITag] object in production.
+  ///
   /// REQUIRED.
   String? name;
 
   /// A short description for the tag.
   ///
+  /// This property provides a brief description of the tag's purpose or the operations it groups.
+  /// According to the OpenAPI Specification, CommonMark syntax MAY be used for rich text representation.
+  ///
+  /// This field is optional and can be null if no description is provided.
+  ///
   /// CommonMark syntax MAY be used for rich text representation.
   String? description;
 
+  /// Decodes the [APITag] object from a [KeyedArchive].
+  ///
+  /// This method is responsible for populating the properties of the [APITag] object
+  /// from a [KeyedArchive]. It decodes the following fields:
+  /// - 'name': The name of the tag (String)
+  /// - 'description': A short description for the tag (String)
+  ///
+  /// This method overrides the [decode] method from the superclass and calls it before
+  /// performing its own decoding operations.
+  ///
+  /// @param object The [KeyedArchive] containing the encoded [APITag] data.
   @override
   void decode(KeyedArchive object) {
     super.decode(object);
@@ -185,6 +580,18 @@ class APITag extends APIObject {
     description = object.decode("description");
   }
 
+  /// Encodes the [APITag] object into a [KeyedArchive].
+  ///
+  /// This method is responsible for serializing the properties of the [APITag] object
+  /// into a [KeyedArchive]. It encodes the following fields:
+  /// - 'name': The name of the tag (String)
+  /// - 'description': A short description for the tag (String)
+  ///
+  /// This method first calls the superclass's encode method, then checks if the required
+  /// 'name' field is non-null. If 'name' is null, it throws an [ArgumentError].
+  ///
+  /// @param object The [KeyedArchive] to encode the [APITag] data into.
+  /// @throws ArgumentError if 'name' is null.
   @override
   void encode(KeyedArchive object) {
     super.encode(object);

packages/openapi/lib/src/v3/operation.dart

@@ -13,7 +13,30 @@ import 'package:protevus_openapi/object.dart';
 import 'package:protevus_openapi/v3.dart';
 
 /// Describes a single API operation on a path.
+///
+/// This class represents an operation (HTTP method) in an OpenAPI specification.
+/// It contains information about the operation such as tags, summary, description,
+/// parameters, security requirements, request body, responses, and more.
+///
+/// The class provides methods to add parameters, security requirements, and responses,
+/// as well as to retrieve specific parameters by name.
+///
+/// This class extends [APIObject] and implements [Codable] for serialization and deserialization.
 class APIOperation extends APIObject {
+  /// Creates a new [APIOperation] instance.
+  ///
+  /// [id] is the unique string used to identify the operation.
+  /// [responses] is a map of possible responses as they are returned from executing this operation.
+  ///
+  /// Optional parameters:
+  /// - [tags]: A list of tags for API documentation control.
+  /// - [summary]: A short summary of what the operation does.
+  /// - [description]: A verbose explanation of the operation behavior.
+  /// - [parameters]: A list of parameters that are applicable for this operation.
+  /// - [security]: A declaration of which security mechanisms can be used for this operation.
+  /// - [requestBody]: The request body applicable for this operation.
+  /// - [callbacks]: A map of possible out-of band callbacks related to the parent operation.
+  /// - [deprecated]: Declares this operation to be deprecated.
   APIOperation(
     this.id,
     this.responses, {
@@ -27,47 +50,159 @@ class APIOperation extends APIObject {
     this.deprecated,
   });
 
+  /// Creates an empty [APIOperation] instance.
+  ///
+  /// This constructor initializes an [APIOperation] with no properties set,
+  /// allowing for manual population of fields after creation.
   APIOperation.empty();
 
   /// A list of tags for API documentation control.
   ///
   /// Tags can be used for logical grouping of operations by resources or any other qualifier.
+  /// These tags are used to categorize and organize API operations in documentation tools and clients.
+  /// Each tag is a string that represents a specific category or group.
+  /// Tags are optional but can greatly improve the organization and discoverability of API operations.
+  /// Multiple tags can be applied to a single operation, allowing for flexible categorization.
   List<String>? tags;
 
   /// A short summary of what the operation does.
+  ///
+  /// This property provides a concise description of the operation's purpose.
+  /// It should be brief, typically a single sentence or short paragraph.
+  /// The summary is often used in API documentation to give users a quick
+  /// understanding of what the operation does without needing to read the
+  /// full description.
   String? summary;
 
   /// A verbose explanation of the operation behavior.
   ///
-  /// CommonMark syntax MAY be used for rich text representation.
+  /// This property provides a detailed description of what the operation does,
+  /// how it works, and any important information that users or developers should
+  /// know about its behavior. It can include information about:
+  /// - The purpose of the operation
+  /// - Expected input and output
+  /// - Possible side effects
+  /// - Usage examples
+  /// - Any limitations or constraints
+  ///
+  /// The description can be more extensive than the summary and is meant to provide
+  /// a comprehensive understanding of the operation.
+  ///
+  /// CommonMark syntax MAY be used for rich text representation, allowing for
+  /// formatted text, lists, code blocks, and other Markdown features to enhance
+  /// readability and organization of the description.
   String? description;
 
   /// Unique string used to identify the operation.
   ///
   /// The id MUST be unique among all operations described in the API. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions.
+  ///
+  /// This property serves as a unique identifier for the operation within the API specification.
+  /// It is crucial for:
+  /// - Distinguishing between different operations
+  /// - Enabling tools and libraries to reference specific operations
+  /// - Maintaining consistency and clarity in API documentation
+  ///
+  /// Best practices for assigning an operationId:
+  /// - Use camelCase naming convention
+  /// - Make it descriptive of the operation's purpose
+  /// - Ensure it's unique across all operations in the API
+  /// - Keep it concise while still being meaningful
+  ///
+  /// Example: 'getUserProfile', 'createOrder', 'updateItemInventory'
+  ///
+  /// Note: While optional in the OpenAPI specification, providing an operationId
+  /// is strongly recommended for better API organization and tooling support.
   String? id;
 
   /// A list of parameters that are applicable for this operation.
   ///
-  /// If a parameter is already defined at the Path Item, the definition will override it but can never remove it. The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a name and location. The list can use the Reference Object to link to parameters that are defined at the OpenAPI Object's components/parameters.
+  /// This property defines the parameters that are specific to this operation.
+  /// These parameters can be in addition to or overriding the parameters defined
+  /// at the path level.
+  ///
+  /// Key points:
+  /// - If a parameter is already defined at the Path Item level, the definition
+  ///   here will override it, but cannot remove it entirely.
+  /// - The list MUST NOT include duplicated parameters. A unique parameter is
+  ///   defined by a combination of a name and location.
+  /// - The list can use the Reference Object to link to parameters that are
+  ///   defined in the OpenAPI Object's components/parameters section.
+  /// - Parameters defined here are specific to this operation and may not apply
+  ///   to other operations, even within the same path.
+  ///
+  /// This property allows for fine-grained control over the parameters for each
+  /// individual operation, enabling precise API documentation and client generation.
   List<APIParameter>? parameters;
 
   /// A declaration of which security mechanisms can be used for this operation.
   ///
-  /// The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. This definition overrides any declared top-level security. To remove a top-level security declaration, an empty array can be used.
+  /// This property defines the security requirements for the specific operation.
+  /// It is represented as a list of [APISecurityRequirement] objects.
+  ///
+  /// Key points:
+  /// - Each element in the list represents an alternative security requirement.
+  /// - Only one of the security requirement objects needs to be satisfied to authorize a request.
+  /// - This definition overrides any declared top-level security for the API.
+  /// - To remove a top-level security declaration, an empty array can be used.
+  /// - If not specified, the security requirements defined at the API level apply.
+  ///
+  /// The security requirements can include various authentication schemes such as:
+  /// - API keys
+  /// - OAuth2 flows
+  /// - OpenID Connect Discovery
+  /// - HTTP authentication schemes (e.g., Basic, Bearer)
+  ///
+  /// By specifying security at the operation level, you can have fine-grained
+  /// control over the security requirements for different API endpoints.
   List<APISecurityRequirement>? security;
 
   /// The request body applicable for this operation.
   ///
-  /// The requestBody is only supported in HTTP methods where the HTTP 1.1 specification RFC7231 has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague, requestBody SHALL be ignored by consumers.
+  /// This property specifies the request body content for this operation. It is represented
+  /// by an [APIRequestBody] object, which describes a single request body.
+  ///
+  /// Key points:
+  /// - The requestBody is only supported in HTTP methods where the HTTP 1.1 specification
+  ///   RFC7231 has explicitly defined semantics for request bodies.
+  /// - In cases where the HTTP spec is vague about request bodies, this property SHALL be
+  ///   ignored by consumers.
+  /// - It can be used to describe the content, format, and schema of the request body.
+  /// - This property is particularly useful for POST, PUT, and PATCH operations.
+  /// - It can specify multiple content types that the API can consume.
+  /// - If null, it indicates that the operation does not expect a request body.
+  ///
+  /// Note: The actual support and behavior regarding request bodies may vary depending on
+  /// the specific HTTP method used and how strictly the implementation follows the HTTP
+  /// specifications.
   APIRequestBody? requestBody;
 
   /// The list of possible responses as they are returned from executing this operation.
   ///
-  /// REQUIRED.
+  /// This property is a map where the keys are HTTP status codes (as strings) and the values
+  /// are [APIResponse] objects describing the response for that status code.
+  ///
+  /// Key points:
+  /// - This property is REQUIRED in the OpenAPI specification.
+  /// - It must contain at least one response object, which may be the 'default' response.
+  /// - The map can use the wildcard HTTP status code '2XX', '3XX', '4XX', or '5XX' to describe
+  ///   multiple status codes at once.
+  /// - The 'default' key can be used to describe the response for all undeclared status codes.
+  ///
+  /// Example:
+  /// ```
+  /// "responses": {
+  ///   "200": { ... },  // Successful response
+  ///   "400": { ... },  // Bad request response
+  ///   "default": { ... }  // Unexpected error response
+  /// }
+  /// ```
+  ///
+  /// Each [APIResponse] object in this map provides details about the response such as
+  /// description, headers, content, and links.
   Map<String, APIResponse?>? responses;
 
-  /// A map of possible out-of band callbacks related to the parent operation.
+  /// A map of possible out-of-band callbacks related to the parent operation.
   ///
   /// The key is a unique identifier for the [APICallback]. Each value in the map is a [APICallback] that describes a request that may be initiated by the API provider and the expected responses. The key value used to identify the callback object is an expression, evaluated at runtime, that identifies a URL to use for the callback operation.
   Map<String, APICallback?>? callbacks;
@@ -75,18 +210,49 @@ class APIOperation extends APIObject {
   /// An alternative server array to service this operation.
   ///
   /// If an alternative server object is specified at the [APIPath] or [APIDocument] level, it will be overridden by this value.
+  ///
+  /// This property allows specifying operation-specific servers, which take precedence over servers defined at the path or document level.
+  /// Each [APIServerDescription] in the list represents a server that can handle requests for this specific operation.
+  ///
+  /// Key points:
+  /// - If specified, this array overrides any server configurations defined at higher levels (path, document).
+  /// - It allows for fine-grained control over which servers can handle specific operations.
+  /// - Useful for scenarios where certain operations are only available on specific servers.
+  /// - Can be used to specify different environments (e.g., production, staging) for different operations.
+  ///
+  /// The list can be null if no operation-specific servers are defined, in which case the servers defined at higher levels will be used.
   List<APIServerDescription?>? servers;
 
   /// Declares this operation to be deprecated.
   ///
-  /// Consumers SHOULD refrain from usage of the declared operation. Default value is false.
+  /// This property indicates whether the operation is deprecated and should be avoided in future use.
+  ///
+  /// Key points:
+  /// - When set to true, it signals that the operation is no longer recommended for use.
+  /// - Consumers of the API SHOULD refrain from using deprecated operations.
+  /// - It helps in managing API lifecycle by indicating which operations are being phased out.
+  /// - Can be used to guide API users towards newer or preferred alternatives.
+  /// - The default value is false if not explicitly set.
+  ///
+  /// Note: Even when an operation is marked as deprecated, it may still be functional.
+  /// However, it's a strong indication that the operation may be removed or altered in future versions of the API.
   bool? deprecated;
 
   /// Returns the parameter named [name] or null if it doesn't exist.
+  ///
+  /// This method searches the [parameters] list for a parameter with the specified [name].
+  /// If found, it returns the matching [APIParameter] object.
+  /// If no parameter with the given name is found, or if [parameters] is null, it returns null.
+  ///
+  /// Parameters:
+  ///   [name]: The name of the parameter to search for.
+  ///
+  /// Returns:
+  ///   An [APIParameter] object if a parameter with the specified name is found, otherwise null.
   APIParameter? parameterNamed(String name) =>
       parameters?.firstWhere((p) => p.name == name);
 
-  /// Adds [parameter] to [parameters].
+  /// Adds a parameter to the list of parameters for this operation.
   ///
   /// If [parameters] is null, invoking this method will set it to a list containing [parameter].
   /// Otherwise, [parameter] is added to [parameters].
@@ -95,7 +261,7 @@ class APIOperation extends APIObject {
     parameters!.add(parameter);
   }
 
-  /// Adds [requirement] to [security].
+  /// Adds a security requirement to the operation's security list.
   ///
   /// If [security] is null, invoking this method will set it to a list containing [requirement].
   /// Otherwise, [requirement] is added to [security].
@@ -107,11 +273,33 @@ class APIOperation extends APIObject {
 
   /// Adds [response] to [responses], merging schemas if necessary.
   ///
-  /// [response] will be added to [responses] for the key [statusCode].
+  /// This method adds the given [response] to the [responses] map using the [statusCode] as the key.
+  /// If a response already exists for the given [statusCode], it merges the new response with the existing one.
   ///
-  /// If a response already exists for this [statusCode], [response]'s content
-  /// and headers are added to the list of possible content and headers for the existing response. Descriptions
-  /// of each response are joined together. All headers are marked as optional..
+  /// Parameters:
+  ///   [statusCode]: The HTTP status code for the response.
+  ///   [response]: The APIResponse object to be added or merged.
+  ///
+  /// Behavior:
+  /// - If [responses] is null, it initializes it as an empty map.
+  /// - If no response exists for the given [statusCode], it simply adds the new response.
+  /// - If a response already exists:
+  ///   - The descriptions are concatenated.
+  ///   - Headers from the new response are added to the existing response.
+  ///   - Content from the new response is added to the existing response.
+  ///
+  /// Note: This method modifies the [responses] property of the current object.
+  ///
+  /// Example:
+  /// ```dart
+  /// var operation = APIOperation.empty();
+  /// var response = APIResponse(...);
+  /// operation.addResponse(200, response);
+  /// ```
+  ///
+  /// This method is useful for building or updating the responses of an API operation,
+  /// allowing for the gradual construction of complex response structures or the
+  /// modification of existing responses without overwriting all information.
   void addResponse(int statusCode, APIResponse? response) {
     responses ??= {};
 
@@ -133,9 +321,42 @@ class APIOperation extends APIObject {
     });
   }
 
+  /// Defines the casting rules for specific properties of this class.
+  ///
+  /// This getter provides a map where the keys are property names and the values
+  /// are [cast.Cast] objects that define how these properties should be cast
+  /// when being decoded or encoded.
+  ///
+  /// In this case, it specifies that the 'tags' property should be cast as a
+  /// List of strings. This ensures that when the 'tags' property is processed,
+  /// it will be treated as a list of string values.
+  ///
+  /// Returns:
+  ///   A Map<String, cast.Cast> where:
+  ///   - The key 'tags' is associated with a cast.List(cast.string) value,
+  ///     indicating that 'tags' should be cast as a list of strings.
   @override
   Map<String, cast.Cast> get castMap => {"tags": const cast.List(cast.string)};
 
+  /// Decodes the properties of this [APIOperation] from a [KeyedArchive] object.
+  ///
+  /// This method is responsible for populating the properties of the [APIOperation]
+  /// instance from the provided [KeyedArchive] object. It decodes various fields
+  /// such as tags, summary, description, parameters, responses, and more.
+  ///
+  /// The method handles different types of properties:
+  /// - Simple properties like 'tags', 'summary', 'description' are directly decoded.
+  /// - Complex properties like 'parameters', 'security', 'servers' are decoded as lists of objects.
+  /// - Map properties like 'responses' and 'callbacks' are decoded as object maps.
+  /// - Objects like 'requestBody' are decoded as single instances.
+  ///
+  /// Some decoded properties (like 'parameters' and 'security') are filtered to remove null values.
+  ///
+  /// This method overrides the 'decode' method from a superclass and calls the superclass
+  /// implementation before performing its own decoding.
+  ///
+  /// Parameters:
+  ///   [object]: The [KeyedArchive] containing the encoded data to be decoded.
   @override
   void decode(KeyedArchive object) {
     super.decode(object);
@@ -161,6 +382,29 @@ class APIOperation extends APIObject {
         object.decodeObjects("servers", () => APIServerDescription.empty());
   }
 
+  /// Encodes the properties of this [APIOperation] into a [KeyedArchive] object.
+  ///
+  /// This method is responsible for serializing the properties of the [APIOperation]
+  /// instance into the provided [KeyedArchive] object. It encodes various fields
+  /// such as tags, summary, description, parameters, responses, and more.
+  ///
+  /// The method handles different types of properties:
+  /// - Simple properties like 'tags', 'summary', 'description' are directly encoded.
+  /// - Complex properties like 'parameters', 'security', 'servers' are encoded as lists of objects.
+  /// - Map properties like 'responses' and 'callbacks' are encoded as object maps.
+  /// - Objects like 'requestBody' are encoded as single instances.
+  ///
+  /// This method throws an [ArgumentError] if the 'responses' property is null,
+  /// as it is a required field in the OpenAPI specification.
+  ///
+  /// This method overrides the 'encode' method from a superclass and calls the superclass
+  /// implementation before performing its own encoding.
+  ///
+  /// Parameters:
+  ///   [object]: The [KeyedArchive] where the encoded data will be stored.
+  ///
+  /// Throws:
+  ///   [ArgumentError]: If the 'responses' property is null.
   @override
   void encode(KeyedArchive object) {
     super.encode(object);

packages/openapi/lib/src/v3/parameter.dart

@@ -11,7 +11,7 @@ import 'package:protevus_typeforge/codable.dart';
 import 'package:protevus_openapi/object.dart';
 import 'package:protevus_openapi/v3.dart';
 
-/// There are four possible parameter locations specified by the in field.
+/// Enumerates the possible locations for parameters in an API request.
 ///
 /// - path:
 /// - query:
@@ -21,23 +21,84 @@ enum APIParameterLocation {
   /// Parameters that are appended to the URL.
   ///
   /// For example, in /items?id=###, the query parameter is id.
+  ///
+  /// Query parameters are used to filter, sort, or provide additional
+  /// information for the requested resource. They appear after the question
+  /// mark (?) in the URL and are separated by ampersands (&) if there are
+  /// multiple parameters.
   query,
 
   /// Custom headers that are expected as part of the request.
   ///
+  /// Headers are additional metadata sent with an HTTP request or response.
+  /// They provide information about the request or response, such as content type,
+  /// authentication tokens, or caching directives.
+  ///
+  /// Examples of common headers include:
+  /// - Content-Type: Specifies the media type of the resource
+  /// - Authorization: Contains credentials for authenticating the client
+  /// - User-Agent: Identifies the client software making the request
+  ///
   /// Note that RFC7230 states header names are case insensitive.
   header,
 
   /// Used together with Path Templating, where the parameter value is actually part of the operation's URL.
   ///
   /// This does not include the host or base path of the API. For example, in /items/{itemId}, the path parameter is itemId.
+  ///
+  /// Path parameters are used to identify a specific resource or resources. They are part of the URL path and are typically
+  /// used to specify the ID of a resource. Path parameters are always required, as they are necessary to construct the full URL.
+  ///
+  /// Examples:
+  /// - /users/{userId}: 'userId' is a path parameter
+  /// - /posts/{postId}/comments/{commentId}: both 'postId' and 'commentId' are path parameters
+  ///
+  /// When defining an API, path parameters are denoted by curly braces {} in the URL template.
   path,
 
   /// Used to pass a specific cookie value to the API.
+  ///
+  /// Cookie parameters are used to send data to the server using HTTP cookies.
+  /// They are typically used for maintaining session state, tracking user preferences,
+  /// or passing authentication tokens.
+  ///
+  /// Cookie parameters are sent in the Cookie HTTP header. Unlike query parameters,
+  /// cookie parameters are not visible in the URL and are sent with every request
+  /// to the domain that set the cookie.
+  ///
+  /// Example of a cookie header:
+  /// Cookie: session_id=abc123; user_preference=dark_mode
+  ///
+  /// Note: Use of cookies should be done with consideration for security and privacy implications.
   cookie
 }
 
+/// A utility class for encoding and decoding [APIParameterLocation] values.
+///
+/// This class provides two static methods:
+/// - [decode]: Converts a string representation of a parameter location to an [APIParameterLocation] enum value.
+/// - [encode]: Converts an [APIParameterLocation] enum value to its string representation.
+///
+/// Both methods handle null values gracefully, returning null if the input is null or not recognized.
+///
+/// Usage:
+/// ```dart
+/// // Decoding a string to APIParameterLocation
+/// APIParameterLocation? location = APIParameterLocationCodec.decode("query");
+/// print(location); // Output: APIParameterLocation.query
+///
+/// // Encoding an APIParameterLocation to a string
+/// String? locationString = APIParameterLocationCodec.encode(APIParameterLocation.path);
+/// print(locationString); // Output: "path"
+/// ```
+///
+/// This class is particularly useful when working with API specifications or
+/// when serializing/deserializing API parameter location data.
 class APIParameterLocationCodec {
+  /// Decodes a string representation of a parameter location to an [APIParameterLocation] enum value.
+  ///
+  /// Returns:
+  ///   The corresponding [APIParameterLocation] enum value, or null if not recognized.
   static APIParameterLocation? decode(String? location) {
     switch (location) {
       case "query":
@@ -53,6 +114,23 @@ class APIParameterLocationCodec {
     }
   }
 
+  /// Encodes an [APIParameterLocation] enum value to its string representation.
+  ///
+  /// This method takes an [APIParameterLocation] enum value [location] and returns
+  /// the corresponding string representation. If the input is null or not recognized,
+  /// the method returns null.
+  ///
+  /// Supported [APIParameterLocation] values and their string representations:
+  /// - [APIParameterLocation.query] returns "query"
+  /// - [APIParameterLocation.header] returns "header"
+  /// - [APIParameterLocation.path] returns "path"
+  /// - [APIParameterLocation.cookie] returns "cookie"
+  ///
+  /// Parameters:
+  ///   [location] - An [APIParameterLocation] enum value to be encoded.
+  ///
+  /// Returns:
+  ///   A [String] representation of the [APIParameterLocation], or null if not recognized.
   static String? encode(APIParameterLocation? location) {
     switch (location) {
       case APIParameterLocation.query:
@@ -69,10 +147,24 @@ class APIParameterLocationCodec {
   }
 }
 
-/// Describes a single operation parameter.
+/// Describes a single operation parameter in an API specification.
 ///
 /// A unique parameter is defined by a combination of a [name] and [location].
 class APIParameter extends APIObject {
+  /// Creates an [APIParameter] instance.
+  ///
+  /// Parameters:
+  /// - [name]: The name of the parameter.
+  /// - [location]: The location of the parameter (query, header, path, or cookie).
+  /// - [description]: A brief description of the parameter.
+  /// - [schema]: The schema defining the type used for the parameter.
+  /// - [content]: A map containing the representations for the parameter.
+  /// - [style]: Describes how the parameter value will be serialized.
+  /// - [isRequired]: Determines whether this parameter is mandatory.
+  /// - [deprecated]: Specifies that a parameter is deprecated.
+  /// - [allowEmptyValue]: Sets the ability to pass empty-valued parameters.
+  /// - [explode]: When true, generates separate parameters for each value of array or object.
+  /// - [allowReserved]: Determines whether the parameter value should allow reserved characters.
   APIParameter(
     this.name,
     this.location, {
@@ -87,8 +179,36 @@ class APIParameter extends APIObject {
     this.allowReserved,
   }) : _required = isRequired;
 
+  /// Creates an empty [APIParameter] instance.
+  ///
+  /// This constructor initializes an [APIParameter] without setting any properties.
+  /// It can be useful when you need to create a parameter object and set its
+  /// properties later, or when you want to create a placeholder parameter.
+  ///
+  /// Example usage:
+  /// ```dart
+  /// var emptyParameter = APIParameter.empty();
+  /// // Properties can be set later
+  /// emptyParameter.name = 'exampleParam';
+  /// emptyParameter.location = APIParameterLocation.query;
+  /// ```
   APIParameter.empty();
 
+  /// Creates an [APIParameter] instance for a header parameter.
+  ///
+  /// This constructor initializes an [APIParameter] with the location set to [APIParameterLocation.header].
+  ///
+  /// Parameters:
+  /// - [name]: The name of the header parameter.
+  /// - [description]: Optional. A brief description of the parameter.
+  /// - [schema]: Optional. The schema defining the type used for the parameter.
+  /// - [content]: Optional. A map containing the representations for the parameter.
+  /// - [style]: Optional. Describes how the parameter value will be serialized.
+  /// - [isRequired]: Optional. Determines whether this parameter is mandatory.
+  /// - [deprecated]: Optional. Specifies that a parameter is deprecated.
+  /// - [allowEmptyValue]: Optional. Sets the ability to pass empty-valued parameters.
+  /// - [explode]: Optional. When true, generates separate parameters for each value of array or object.
+  /// - [allowReserved]: Optional. Determines whether the parameter value should allow reserved characters.
   APIParameter.header(
     this.name, {
     this.description,
@@ -104,6 +224,21 @@ class APIParameter extends APIObject {
     location = APIParameterLocation.header;
   }
 
+  /// Creates an [APIParameter] instance for a query parameter.
+  ///
+  /// This constructor initializes an [APIParameter] with the location set to [APIParameterLocation.query].
+  ///
+  /// Parameters:
+  /// - [name]: The name of the query parameter.
+  /// - [description]: Optional. A brief description of the parameter.
+  /// - [schema]: Optional. The schema defining the type used for the parameter.
+  /// - [content]: Optional. A map containing the representations for the parameter.
+  /// - [style]: Optional. Describes how the parameter value will be serialized.
+  /// - [isRequired]: Optional. Determines whether this parameter is mandatory.
+  /// - [deprecated]: Optional. Specifies that a parameter is deprecated.
+  /// - [allowEmptyValue]: Optional. Sets the ability to pass empty-valued parameters.
+  /// - [explode]: Optional. When true, generates separate parameters for each value of array or object.
+  /// - [allowReserved]: Optional. Determines whether the parameter value should allow reserved characters.
   APIParameter.query(
     this.name, {
     this.description,
@@ -119,11 +254,40 @@ class APIParameter extends APIObject {
     location = APIParameterLocation.query;
   }
 
+  /// Creates an [APIParameter] instance for a path parameter.
+  ///
+  /// This constructor initializes an [APIParameter] with the following properties:
+  /// - [location] is set to [APIParameterLocation.path]
+  /// - [schema] is set to a string schema using [APISchemaObject.string()]
+  /// - [_required] is set to true, as path parameters are always required
+  ///
+  /// Parameters:
+  /// - [name]: The name of the path parameter.
+  ///
+  /// Usage:
+  /// ```dart
+  /// var pathParam = APIParameter.path('userId');
+  /// ```
   APIParameter.path(this.name)
       : location = APIParameterLocation.path,
         schema = APISchemaObject.string(),
         _required = true;
 
+  /// Creates an [APIParameter] instance for a cookie parameter.
+  ///
+  /// This constructor initializes an [APIParameter] with the location set to [APIParameterLocation.cookie].
+  ///
+  /// Parameters:
+  /// - [name]: The name of the cookie parameter.
+  /// - [description]: Optional. A brief description of the parameter.
+  /// - [schema]: Optional. The schema defining the type used for the parameter.
+  /// - [content]: Optional. A map containing the representations for the parameter.
+  /// - [style]: Optional. Describes how the parameter value will be serialized.
+  /// - [isRequired]: Optional. Determines whether this parameter is mandatory.
+  /// - [deprecated]: Optional. Specifies that a parameter is deprecated.
+  /// - [allowEmptyValue]: Optional. Sets the ability to pass empty-valued parameters.
+  /// - [explode]: Optional. When true, generates separate parameters for each value of array or object.
+  /// - [allowReserved]: Optional. Determines whether the parameter value should allow reserved characters.
   APIParameter.cookie(
     this.name, {
     this.description,
@@ -141,20 +305,47 @@ class APIParameter extends APIObject {
 
   /// The name of the parameter.
   ///
-  /// REQUIRED. Parameter names are case sensitive.
-  /// If in is "path", the name field MUST correspond to the associated path segment from the path field in [APIDocument.paths]. See Path Templating for further information.
-  /// If in is "header" and the name field is "Accept", "Content-Type" or "Authorization", the parameter definition SHALL be ignored.
-  /// For all other cases, the name corresponds to the parameter name used by the in property.
+  /// This property is REQUIRED for all parameters. The name is case sensitive and must be unique within the parameter list.
+  ///
+  /// Specific behavior based on the parameter location:
+  /// - If [location] is "path", the name MUST correspond to a path segment in the [APIDocument.paths] field.
+  /// - If [location] is "header" and the name is "Accept", "Content-Type", or "Authorization", the parameter definition will be ignored.
+  /// - For all other cases, the name corresponds to the parameter name used by the [location] property.
+  ///
+  /// See Path Templating in the OpenAPI Specification for more information on path parameters.
+  ///
+  /// Note: This field is nullable in the class definition, but should be non-null when used in a valid API specification.
   String? name;
 
   /// A brief description of the parameter.
   ///
-  /// This could contain examples of use. CommonMark syntax MAY be used for rich text representation.
+  /// This property provides a short explanation of the parameter's purpose, usage, or any other relevant information.
+  /// It can include examples to illustrate how the parameter should be used.
+  ///
+  /// The description supports CommonMark syntax, allowing for rich text formatting such as bold, italic, lists, and more.
+  /// This enables clear and structured documentation of the parameter.
+  ///
+  /// Example:
+  /// ```
+  /// description: "The **user's age** in years. Must be a positive integer."
+  /// ```
+  ///
+  /// Note: This property is optional but highly recommended for clear API documentation.
   String? description;
 
   /// Determines whether this parameter is mandatory.
   ///
-  /// If the parameter location is "path", this property is REQUIRED and its value MUST be true. Otherwise, the property MAY be included and its default value is false.
+  /// This property is implemented as a getter and setter pair.
+  ///
+  /// The getter:
+  /// - Returns true if the parameter location is "path", regardless of the value of _required.
+  /// - Otherwise, returns the value of _required.
+  ///
+  /// The setter:
+  /// - Sets the value of _required to the provided boolean value.
+  ///
+  /// Note: If the parameter location is "path", this property is REQUIRED and its value MUST be true.
+  /// For other locations, the property MAY be included and its default value is false.
   bool? get isRequired =>
       location == APIParameterLocation.path ? true : _required;
 
@@ -162,48 +353,178 @@ class APIParameter extends APIObject {
     _required = f;
   }
 
+  /// Stores the required status of the parameter.
+  ///
+  /// This private field is used to back the [isRequired] property.
+  /// It's nullable to allow for cases where the required status is not explicitly set.
+  ///
+  /// Note: For path parameters, this value is ignored as they are always required.
+  /// For other parameter types, if not set, it defaults to false.
   bool? _required;
 
   /// Specifies that a parameter is deprecated and SHOULD be transitioned out of usage.
-
+  ///
+  /// When set to true, it indicates that the parameter is deprecated and consumers of the API
+  /// should refrain from using it. This allows API providers to gradually phase out parameters
+  /// while maintaining backward compatibility.
+  ///
+  /// Default value is false (not deprecated) when not specified.
+  ///
+  /// Example usage:
+  /// ```dart
+  /// var parameter = APIParameter('oldParam', APIParameterLocation.query);
+  /// parameter.deprecated = true;
+  /// ```
   bool? deprecated;
 
   /// The location of the parameter.
   ///
-  /// REQUIRED. Possible values are "query", "header", "path" or "cookie".
+  /// This property specifies where the parameter is expected to be found in the API request.
+  /// It is a REQUIRED field for all parameter objects.
+  ///
+  /// The value must be one of the following:
+  /// - "query": The parameter is part of the query string in the URL.
+  /// - "header": The parameter is included as an HTTP header.
+  /// - "path": The parameter is part of the URL path.
+  /// - "cookie": The parameter is sent as an HTTP cookie.
+  ///
+  /// This field uses the [APIParameterLocation] enum to ensure type safety and
+  /// to restrict the possible values to the allowed set.
+  ///
+  /// Note: Although this field is nullable in the class definition, it should always
+  /// be set to a non-null value when used in a valid API specification.
   APIParameterLocation? location;
 
   /// The schema defining the type used for the parameter.
+  ///
+  /// This property defines the structure and constraints of the parameter value.
+  /// It can specify the data type, format, validation rules, and other characteristics
+  /// of the parameter.
+  ///
+  /// The schema is represented by an [APISchemaObject], which allows for detailed
+  /// specification of simple types (like strings or integers) as well as complex
+  /// structures (like objects or arrays).
+  ///
+  /// This property is mutually exclusive with the [content] property. When using
+  /// [schema], the serialization rules for the parameter are defined by the
+  /// [style] and [explode] fields.
+  ///
+  /// Example usage:
+  /// ```dart
+  /// parameter.schema = APISchemaObject.string(format: 'email');
+  /// ```
   APISchemaObject? schema;
 
-  // Sets the ability to pass empty-valued parameters.
-  //
-  // This is valid only for query parameters and allows sending a parameter with an empty value. Default value is false. If style is used, and if behavior is n/a (cannot be serialized), the value of allowEmptyValue SHALL be ignored.
+  /// Sets the ability to pass empty-valued parameters.
+  ///
+  /// This property is only applicable for query parameters and allows sending a parameter with an empty value.
+  /// The default value is false.
+  ///
+  /// Note: If [style] is used, and if the behavior is not applicable (cannot be serialized),
+  /// the value of [allowEmptyValue] SHALL be ignored.
+  ///
+  /// Example usage:
+  /// ```dart
+  /// var parameter = APIParameter('queryParam', APIParameterLocation.query);
+  /// parameter.allowEmptyValue = true;
+  /// ```
   bool? allowEmptyValue = false;
 
   /// Describes how the parameter value will be serialized depending on the type of the parameter value.
   ///
-  /// Default values (based on value of in): for query - form; for path - simple; for header - simple; for cookie - form.
+  /// This property determines the format in which the parameter value should be serialized when sent in the request.
+  /// The appropriate serialization method depends on both the parameter's location and its data type.
+  ///
+  /// Default values (based on the value of 'in' property):
+  /// - For query parameters: "form"
+  /// - For path parameters: "simple"
+  /// - For header parameters: "simple"
+  /// - For cookie parameters: "form"
+  ///
+  /// Possible values include:
+  /// - "matrix"
+  /// - "label"
+  /// - "form"
+  /// - "simple"
+  /// - "spaceDelimited"
+  /// - "pipeDelimited"
+  /// - "deepObject"
+  ///
+  /// The exact behavior and applicability of each style depend on the parameter's location and data type.
+  /// Refer to the OpenAPI Specification for detailed information on how each style affects serialization.
   String? style;
 
-  /// When this is true, parameter values of type array or object generate separate parameters for each value of the array or key-value pair of the map.
+  /// Specifies whether array or object parameters should be expanded into multiple parameters.
   ///
   /// For other types of parameters this property has no effect. When style is form, the default value is true. For all other styles, the default value is false.
   bool? explode = false;
 
   /// Determines whether the parameter value SHOULD allow reserved characters, as defined by RFC3986 :/?#[]@!$&'()*+,;= to be included without percent-encoding.
   ///
-  /// This property only applies to parameters with an in value of query. The default value is false.
+  /// This property only applies to parameters with an 'in' value of query. The default value is false.
+  ///
+  /// When set to true, reserved characters in the parameter value are allowed to be included without percent-encoding.
+  /// This can be useful in cases where you want to pass special characters directly in the query string.
+  ///
+  /// Example:
+  /// If allowReserved is true, a query parameter like "filter=name:John/age:30" could be sent as-is.
+  /// If false, it would need to be encoded as "filter=name%3AJohn%2Fage%3A30".
+  ///
+  /// Note: Use this property with caution, as it may affect how the server interprets the parameter value.
+  /// It's recommended to keep this false unless you have a specific reason to allow reserved characters.
   bool? allowReserved = false;
 
   /// A map containing the representations for the parameter.
   ///
-  /// The key is the media type and the value describes it. The map MUST only contain one entry.
+  /// The key is a media type and the value describes it. The map MUST only contain one entry.
+  ///
+  /// This property is mutually exclusive with the [schema] property. It can be used to describe
+  /// complex parameter structures or to specify alternative representations of the parameter value.
+  ///
+  /// The media type (key) should be a string representing the MIME type of the content,
+  /// such as "application/json" or "text/plain".
+  ///
+  /// Each [APIMediaType] value provides detailed information about the content,
+  /// including its schema, examples, and encoding properties.
+  ///
+  /// Example usage:
+  /// ```dart
+  /// parameter.content = {
+  ///   'application/json': APIMediaType(
+  ///     schema: APISchemaObject.object({
+  ///       'name': APISchemaObject.string(),
+  ///       'age': APISchemaObject.integer(),
+  ///     })
+  ///   )
+  /// };
+  /// ```
+  ///
+  /// Note: While the map allows for multiple entries, according to the OpenAPI Specification,
+  /// it MUST only contain one entry for parameter objects.
   Map<String, APIMediaType?>? content;
 
-  // Currently missing:
-  // example, examples
-
+  /// Decodes an [APIParameter] object from a [KeyedArchive].
+  ///
+  /// This method populates the properties of the [APIParameter] instance
+  /// by decoding values from the provided [KeyedArchive] object.
+  ///
+  /// The following properties are decoded:
+  /// - name: The name of the parameter
+  /// - description: A brief description of the parameter
+  /// - location: The location of the parameter (query, header, path, or cookie)
+  /// - _required: Whether the parameter is required
+  /// - deprecated: Whether the parameter is deprecated
+  /// - allowEmptyValue: Whether empty values are allowed for this parameter
+  /// - schema: The schema defining the type used for the parameter
+  /// - style: Describes how the parameter value will be serialized
+  /// - explode: Whether to expand array or object parameters
+  /// - allowReserved: Whether the parameter value should allow reserved characters
+  /// - content: A map containing the representations for the parameter
+  ///
+  /// Note: This method does not currently decode 'example' and 'examples' properties.
+  ///
+  /// Parameters:
+  ///   object: The [KeyedArchive] containing the encoded [APIParameter] data.
   @override
   void decode(KeyedArchive object) {
     super.decode(object);
@@ -223,6 +544,33 @@ class APIParameter extends APIObject {
     content = object.decodeObjectMap("content", () => APIMediaType());
   }
 
+  /// Encodes the [APIParameter] object into a [KeyedArchive].
+  ///
+  /// This method serializes the properties of the [APIParameter] instance
+  /// into the provided [KeyedArchive] object for storage or transmission.
+  ///
+  /// The following properties are encoded:
+  /// - name: The name of the parameter
+  /// - description: A brief description of the parameter
+  /// - location: The location of the parameter (query, header, path, or cookie)
+  /// - required: Whether the parameter is required (always true for path parameters)
+  /// - deprecated: Whether the parameter is deprecated
+  /// - allowEmptyValue: Whether empty values are allowed (only for query parameters)
+  /// - schema: The schema defining the type used for the parameter
+  /// - style: Describes how the parameter value will be serialized
+  /// - explode: Whether to expand array or object parameters
+  /// - allowReserved: Whether the parameter value should allow reserved characters
+  /// - content: A map containing the representations for the parameter
+  ///
+  /// This method also performs a validation check to ensure that both 'name'
+  /// and 'location' properties are non-null. If either of these properties
+  /// is null, it throws an [ArgumentError].
+  ///
+  /// Parameters:
+  ///   object: The [KeyedArchive] where the encoded data will be stored.
+  ///
+  /// Throws:
+  ///   ArgumentError: If either 'name' or 'location' is null.
   @override
   void encode(KeyedArchive object) {
     super.encode(object);

packages/openapi/lib/src/v3/path.dart

@@ -11,10 +11,16 @@ import 'package:protevus_typeforge/codable.dart';
 import 'package:protevus_openapi/object.dart';
 import 'package:protevus_openapi/v3.dart';
 
-/// Describes the operations available on a single path.
+/// Represents a path in an API specification.
 ///
 /// An [APIPath] MAY be empty, due to ACL constraints. The path itself is still exposed to the documentation viewer but they will not know which operations and parameters are available.
 class APIPath extends APIObject {
+  /// Constructs an [APIPath] instance.
+  ///
+  /// [summary] is an optional string summary, intended to apply to all operations in this path.
+  /// [description] is an optional string description, intended to apply to all operations in this path.
+  /// [parameters] is a list of parameters applicable for all operations described under this path. Defaults to an empty list if not provided.
+  /// [operations] is a map of HTTP methods to their corresponding [APIOperation] objects. Defaults to an empty map if not provided.
   APIPath({
     this.summary,
     this.description,
@@ -24,29 +30,69 @@ class APIPath extends APIObject {
     this.parameters = parameters ?? [];
     this.operations = operations ?? {};
   }
+
+  /// Creates an empty [APIPath] instance.
+  ///
+  /// This constructor initializes an [APIPath] with an empty list of parameters
+  /// and an empty map of operations. It's useful when you need to create an
+  /// [APIPath] instance without any initial data, which can be populated later.
   APIPath.empty()
       : parameters = <APIParameter?>[],
         operations = <String, APIOperation?>{};
 
   /// An optional, string summary, intended to apply to all operations in this path.
+  ///
+  /// This property provides a brief overview or summary that is applicable to all
+  /// operations defined within this path. It can be used to quickly convey the
+  /// general purpose or functionality of the path without going into specific details
+  /// of individual operations.
   String? summary;
 
   /// An optional, string description, intended to apply to all operations in this path.
   ///
+  /// This property provides a more detailed explanation that is applicable to all
+  /// operations defined within this path. It can be used to offer comprehensive
+  /// information about the path's purpose, usage, or any other relevant details.
+  ///
+  /// The description supports CommonMark syntax, allowing for rich text representation.
+  /// This enables the use of formatted text, links, lists, and other markdown elements
+  /// to create more readable and informative descriptions.
+  ///
   /// CommonMark syntax MAY be used for rich text representation.
   String? description;
 
   /// A list of parameters that are applicable for all the operations described under this path.
   ///
-  /// These parameters can be overridden at the operation level, but cannot be removed there. The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a name and location. The list can use the Reference Object to link to parameters that are defined at the OpenAPI Object's components/parameters.
+  /// These parameters can be overridden at the operation level, but cannot be removed there.
+  /// The list MUST NOT include duplicated parameters. A unique parameter is defined by a
+  /// combination of a name and location. The list can use the Reference Object to link to
+  /// parameters that are defined at the OpenAPI Object's components/parameters.
+  ///
+  /// This property is marked as 'late' to allow for delayed initialization. It holds a list
+  /// of [APIParameter] objects, where each object represents a parameter applicable to all
+  /// operations under this path. The list may contain null values, which should be handled
+  /// appropriately when processing the parameters.
+  ///
+  /// The parameters defined here serve as default parameters for all operations in this path,
+  /// providing a way to specify common parameters without repeating them for each operation.
   late List<APIParameter?> parameters;
 
   /// Definitions of operations on this path.
   ///
-  /// Keys are lowercased HTTP methods, e.g. get, put, delete, post, etc.
+  /// A map where keys are lowercased HTTP methods (e.g., get, put, delete, post)
+  /// and values are corresponding [APIOperation] objects.
+  ///
+  /// This property defines the available operations for this path, associating
+  /// each HTTP method with its specific operation details. The use of lowercase
+  /// keys ensures consistency and case-insensitive matching of HTTP methods.
+  ///
+  /// The map may contain null values, which should be handled appropriately
+  /// when processing the operations. This property is marked as 'late' to allow
+  /// for delayed initialization, typically done in the constructor or a dedicated
+  /// initialization method.
   late Map<String, APIOperation?> operations;
 
-  /// Returns true if this path has path parameters [parameterNames].
+  /// Checks if this path contains specific path parameters.
   ///
   /// Returns true if [parameters] contains path parameters with names that match [parameterNames] and
   /// both lists have the same number of elements.
@@ -64,6 +110,22 @@ class APIPath extends APIObject {
 
   // todo (joeconwaystk): alternative servers not yet implemented
 
+  /// Decodes the [APIPath] instance from a [KeyedArchive] object.
+  ///
+  /// This method populates the properties of the [APIPath] instance using data
+  /// from the provided [KeyedArchive] object. It decodes the following properties:
+  ///
+  /// - [summary]: A brief summary of the path.
+  /// - [description]: A detailed description of the path.
+  /// - [parameters]: A list of [APIParameter] objects applicable to all operations in this path.
+  /// - [operations]: A map of HTTP methods to their corresponding [APIOperation] objects.
+  ///
+  /// The method first calls the superclass's decode method, then decodes each specific
+  /// property. For [parameters], it uses a factory function to create empty [APIParameter]
+  /// instances if needed. For [operations], it checks for the presence of each HTTP method
+  /// in the archive and decodes the corresponding [APIOperation] if present.
+  ///
+  /// @param object The [KeyedArchive] object containing the encoded data.
   @override
   void decode(KeyedArchive object) {
     super.decode(object);
@@ -92,6 +154,22 @@ class APIPath extends APIObject {
     }
   }
 
+  /// Encodes the [APIPath] instance into a [KeyedArchive] object.
+  ///
+  /// This method serializes the properties of the [APIPath] instance into the provided
+  /// [KeyedArchive] object. It encodes the following properties:
+  ///
+  /// - [summary]: A brief summary of the path.
+  /// - [description]: A detailed description of the path.
+  /// - [parameters]: A list of [APIParameter] objects applicable to all operations in this path.
+  /// - [operations]: A map of HTTP methods to their corresponding [APIOperation] objects.
+  ///
+  /// The method first calls the superclass's encode method, then encodes each specific
+  /// property. For [parameters], it only encodes the list if it's not empty. For [operations],
+  /// it iterates through the map and encodes each operation, ensuring the HTTP method names
+  /// are in lowercase.
+  ///
+  /// @param object The [KeyedArchive] object to encode the data into.
   @override
   void encode(KeyedArchive object) {
     super.encode(object);

packages/openapi/lib/src/v3/request_body.dart

@@ -11,12 +11,50 @@ import 'package:protevus_typeforge/codable.dart';
 import 'package:protevus_openapi/object.dart';
 import 'package:protevus_openapi/v3.dart';
 
-/// Describes a single request body.
+/// Describes a single request body in an API specification.
+///
+/// This class represents a request body as defined in the OpenAPI Specification.
+/// It includes information about the content of the request body, an optional
+/// description, and whether the request body is required.
+///
+/// The class provides three constructors:
+/// - A default constructor that takes content, description, and isRequired.
+/// - An empty constructor.
+/// - A schema constructor that creates a request body from a schema object.
+///
+/// The class also implements encoding and decoding methods for serialization.
 class APIRequestBody extends APIObject {
+  /// Creates a new [APIRequestBody] instance.
+  ///
+  /// [content] is a required parameter that represents the content of the request body.
+  /// It's a map where keys are media types and values are [APIMediaType] objects.
+  ///
+  /// [description] is an optional parameter that provides a brief description of the request body.
+  ///
+  /// [isRequired] is an optional parameter that determines if the request body is required in the request.
+  /// It defaults to false if not specified.
   APIRequestBody(this.content, {this.description, this.isRequired = false});
 
+  /// Creates an empty [APIRequestBody] instance.
+  ///
+  /// This constructor initializes a new [APIRequestBody] with no content,
+  /// description, or required status. It can be used as a placeholder or
+  /// when you need to create an instance that will be populated later.
   APIRequestBody.empty();
 
+  /// Creates an [APIRequestBody] instance from a schema object.
+  ///
+  /// This constructor initializes a new [APIRequestBody] using an [APISchemaObject].
+  ///
+  /// Parameters:
+  /// - [schema]: An [APISchemaObject] that defines the structure of the request body.
+  /// - [contentTypes]: An iterable of strings representing the content types for the request body.
+  ///   Defaults to ["application/json"].
+  /// - [description]: An optional description of the request body.
+  /// - [isRequired]: A boolean indicating whether the request body is required. Defaults to false.
+  ///
+  /// The constructor creates a [content] map where each content type in [contentTypes]
+  /// is associated with an [APIMediaType] object containing the provided [schema].
   APIRequestBody.schema(
     APISchemaObject schema, {
     Iterable<String> contentTypes = const ["application/json"],
@@ -31,19 +69,63 @@ class APIRequestBody extends APIObject {
 
   /// A brief description of the request body.
   ///
-  /// This could contain examples of use. CommonMark syntax MAY be used for rich text representation.
+  /// This property provides a short explanation of the request body's purpose or content.
+  /// It can include examples of how to use the request body.
+  ///
+  /// The description supports CommonMark syntax for rich text formatting,
+  /// allowing for more detailed and structured explanations.
+  ///
+  /// This field is optional and can be null if no description is provided.
   String? description;
 
   /// The content of the request body.
   ///
-  /// REQUIRED. The key is a media type or media type range and the value describes it. For requests that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
+  /// This property is a map where the keys are media types or media type ranges,
+  /// and the values are [APIMediaType] objects describing the content.
+  ///
+  /// REQUIRED. The content must be provided for the request body to be valid.
+  ///
+  /// For requests that match multiple keys, only the most specific key is applicable.
+  /// For example, 'text/plain' would override 'text/*'.
+  ///
+  /// Example:
+  /// ```dart
+  /// content = {
+  ///   'application/json': APIMediaType(...),
+  ///   'text/plain': APIMediaType(...),
+  /// };
+  /// ```
+  ///
+  /// Note: Despite being marked as nullable (Map<String, APIMediaType?>?),
+  /// this property is required for a valid APIRequestBody. The nullability
+  /// is likely for serialization purposes.
   Map<String, APIMediaType?>? content;
 
   /// Determines if the request body is required in the request.
   ///
-  /// Defaults to false.
+  /// This boolean property indicates whether the request body is mandatory for the API request.
+  /// When set to true, the client must include the request body in the API call.
+  /// When set to false, the request body is optional.
+  ///
+  /// In the OpenAPI Specification, this corresponds to the 'required' field of the Request Body Object.
+  ///
+  /// Defaults to false, meaning the request body is optional unless explicitly set to true.
   bool isRequired = false;
 
+  /// Decodes the [APIRequestBody] object from a [KeyedArchive].
+  ///
+  /// This method overrides the [decode] method from the superclass and is responsible
+  /// for populating the properties of the [APIRequestBody] instance from the provided
+  /// [KeyedArchive] object.
+  ///
+  /// The method performs the following actions:
+  /// 1. Calls the superclass's decode method.
+  /// 2. Decodes the 'description' field from the archive.
+  /// 3. Decodes the 'required' field, defaulting to false if not present.
+  /// 4. Decodes the 'content' field as an object map of [APIMediaType] instances.
+  ///
+  /// Parameters:
+  /// - [object]: A [KeyedArchive] containing the encoded [APIRequestBody] data.
   @override
   void decode(KeyedArchive object) {
     super.decode(object);
@@ -53,6 +135,24 @@ class APIRequestBody extends APIObject {
     content = object.decodeObjectMap("content", () => APIMediaType());
   }
 
+  /// Encodes the [APIRequestBody] object into a [KeyedArchive].
+  ///
+  /// This method overrides the [encode] method from the superclass and is responsible
+  /// for encoding the properties of the [APIRequestBody] instance into the provided
+  /// [KeyedArchive] object.
+  ///
+  /// The method performs the following actions:
+  /// 1. Calls the superclass's encode method.
+  /// 2. Checks if the 'content' property is null, throwing an ArgumentError if it is.
+  /// 3. Encodes the 'description' field into the archive.
+  /// 4. Encodes the 'required' field into the archive.
+  /// 5. Encodes the 'content' field as an object map into the archive.
+  ///
+  /// Parameters:
+  /// - [object]: A [KeyedArchive] where the encoded [APIRequestBody] data will be stored.
+  ///
+  /// Throws:
+  /// - [ArgumentError]: If the 'content' property is null.
   @override
   void encode(KeyedArchive object) {
     super.encode(object);

packages/openapi/lib/src/v3/response.dart

@@ -11,10 +11,75 @@ import 'package:protevus_typeforge/codable.dart';
 import 'package:protevus_openapi/object.dart';
 import 'package:protevus_openapi/v3.dart';
 
-/// Describes a single response from an API Operation, including design-time, static links to operations based on the response.
+/// Represents an API response as defined in the OpenAPI Specification.
+///
+/// This class models a single response from an API operation, including its description,
+/// headers, and content. It provides methods to add headers and content, as well as
+/// functionality to encode and decode the response object.
+///
+/// The [description] field is required and provides a short description of the response.
+/// The [headers] field is a map of header names to their definitions.
+/// The [content] field is a map of media types to their corresponding media type objects.
+///
+/// This class also includes utility methods:
+/// - [addHeader]: Adds a header to the response
+/// - [addContent]: Adds content to the response for a specific content type
+///
+/// The class implements [Codable] for easy serialization and deserialization.
 class APIResponse extends APIObject {
+  /// Creates a new [APIResponse] instance.
+  ///
+  /// [description] is a required parameter that provides a short description of the response.
+  /// [content] is an optional parameter that represents a map of media types to their corresponding media type objects.
+  /// [headers] is an optional parameter that represents a map of header names to their definitions.
+  ///
+  /// Example:
+  /// ```dart
+  /// var response = APIResponse(
+  ///   'Successful response',
+  ///   content: {'application/json': APIMediaType(schema: someSchema)},
+  ///   headers: {'X-Rate-Limit': APIHeader()},
+  /// );
+  /// ```
   APIResponse(this.description, {this.content, this.headers});
+
+  /// Creates an empty [APIResponse] instance.
+  ///
+  /// This constructor initializes an [APIResponse] without any predefined values.
+  /// It can be useful when you need to create an empty response object that will be
+  /// populated later or when you want to start with a blank slate.
+  ///
+  /// Example:
+  /// ```dart
+  /// var emptyResponse = APIResponse.empty();
+  /// // Later, populate the response as needed
+  /// emptyResponse.description = 'A description';
+  /// emptyResponse.addContent('application/json', someSchemaObject);
+  /// ```
   APIResponse.empty();
+
+  /// Creates an [APIResponse] instance with a schema.
+  ///
+  /// This constructor initializes an [APIResponse] with a given [description] and [schema].
+  /// It allows specifying multiple content types for the same schema.
+  ///
+  /// [description] is a required parameter that provides a short description of the response.
+  /// [schema] is the [APISchemaObject] that defines the structure of the response body.
+  /// [contentTypes] is an optional iterable of content type strings. It defaults to ["application/json"].
+  /// [headers] is an optional parameter that represents a map of header names to their definitions.
+  ///
+  /// The constructor creates a [content] map where each content type in [contentTypes]
+  /// is associated with an [APIMediaType] containing the provided [schema].
+  ///
+  /// Example:
+  /// ```dart
+  /// var response = APIResponse.schema(
+  ///   'Successful response',
+  ///   someSchemaObject,
+  ///   contentTypes: ['application/json', 'application/xml'],
+  ///   headers: {'X-Rate-Limit': APIHeader()},
+  /// );
+  /// ```
   APIResponse.schema(
     this.description,
     APISchemaObject schema, {
@@ -29,23 +94,69 @@ class APIResponse extends APIObject {
 
   /// A short description of the response.
   ///
-  /// REQUIRED. CommonMark syntax MAY be used for rich text representation.
+  /// This property is REQUIRED according to the OpenAPI Specification.
+  /// It provides a brief explanation of the API response.
+  ///
+  /// The description can use CommonMark syntax for rich text representation,
+  /// allowing for formatted text, links, and other markup features.
+  ///
+  /// Example:
+  /// ```dart
+  /// var response = APIResponse('Successful response with user data');
+  /// ```
+  ///
+  /// Note: While the property is marked as nullable (String?), it is a required
+  /// field in the OpenAPI Specification and should be provided when creating
+  /// an APIResponse object.
   String? description;
 
   /// Maps a header name to its definition.
   ///
-  /// RFC7230 states header names are case insensitive. If a response header is defined with the name "Content-Type", it SHALL be ignored.
+  /// This property represents a map of HTTP headers that may be part of the API response.
+  /// Each key in the map is a header name (case-insensitive), and the corresponding value
+  /// is an [APIHeader] object that defines the header's properties.
+  ///
+  /// According to RFC7230, header names are case-insensitive. It's important to note that
+  /// if a response header is defined with the name "Content-Type", it SHALL be ignored.
+  /// This is because the content type is typically handled separately in API specifications.
+  ///
+  /// The map is nullable, allowing for responses that don't include any custom headers.
+  ///
+  /// Example:
+  /// ```dart
+  /// var response = APIResponse('Success');
+  /// response.headers = {
+  ///   'X-Rate-Limit': APIHeader(description: 'Calls per hour allowed by the user'),
+  ///   'X-Expires-After': APIHeader(description: 'Date in UTC when token expires')
+  /// };
+  /// ```
   Map<String, APIHeader?>? headers;
 
   /// A map containing descriptions of potential response payloads.
   ///
-  /// The key is a media type or media type range and the value describes it. For responses that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
+  /// This property represents the content of the API response for different media types.
+  /// The key is a media type or media type range (e.g., 'application/json', 'text/*'),
+  /// and the value is an [APIMediaType] object describing the content for that media type.
+  ///
+  /// For responses that match multiple keys, only the most specific key is applicable.
+  /// For example, 'text/plain' would override 'text/*'.
+  ///
+  /// This property is nullable, allowing for responses that don't include any content.
+  ///
+  /// Example:
+  /// ```dart
+  /// var response = APIResponse('Success');
+  /// response.content = {
+  ///   'application/json': APIMediaType(schema: someJsonSchema),
+  ///   'application/xml': APIMediaType(schema: someXmlSchema)
+  /// };
+  /// ```
   Map<String, APIMediaType?>? content;
 
   // Currently missing:
   // links
 
-  /// Adds a [header] to [headers] for [name].
+  /// Adds a header to the [headers] map of the API response.
   ///
   /// If [headers] is null, it is created. If the key does not exist in [headers], [header] is added for the key.
   /// If the key exists, [header] is not added. (To replace a header, access [headers] directly.)
@@ -56,7 +167,7 @@ class APIResponse extends APIObject {
     }
   }
 
-  /// Adds a [bodyObject] to [content] for a content-type.
+  /// Adds a [bodyObject] to [content] for a specific content type.
   ///
   /// [contentType] must take the form 'primaryType/subType', e.g. 'application/json'. Do not include charsets.
   ///
@@ -81,6 +192,19 @@ class APIResponse extends APIObject {
     }
   }
 
+  /// Decodes the [APIResponse] object from a [KeyedArchive].
+  ///
+  /// This method is part of the [Codable] interface implementation. It populates
+  /// the properties of the [APIResponse] object from a [KeyedArchive] object,
+  /// which typically represents a serialized form of the response.
+  ///
+  /// The method performs the following actions:
+  /// 1. Calls the superclass's decode method to handle any inherited properties.
+  /// 2. Decodes the 'description' field from the archive.
+  /// 3. Decodes the 'content' field as a map of [APIMediaType] objects.
+  /// 4. Decodes the 'headers' field as a map of [APIHeader] objects.
+  ///
+  /// [object] is the [KeyedArchive] containing the encoded [APIResponse] data.
   @override
   void decode(KeyedArchive object) {
     super.decode(object);
@@ -90,6 +214,22 @@ class APIResponse extends APIObject {
     headers = object.decodeObjectMap("headers", () => APIHeader());
   }
 
+  /// Encodes the [APIResponse] object into a [KeyedArchive].
+  ///
+  /// This method is part of the [Codable] interface implementation. It serializes
+  /// the properties of the [APIResponse] object into a [KeyedArchive] object,
+  /// which can then be used for storage or transmission.
+  ///
+  /// The method performs the following actions:
+  /// 1. Calls the superclass's encode method to handle any inherited properties.
+  /// 2. Checks if the 'description' field is non-null, throwing an [ArgumentError] if it's null.
+  /// 3. Encodes the 'description' field into the archive.
+  /// 4. Encodes the 'headers' field as a map of [APIHeader] objects.
+  /// 5. Encodes the 'content' field as a map of [APIMediaType] objects.
+  ///
+  /// [object] is the [KeyedArchive] where the [APIResponse] data will be encoded.
+  ///
+  /// Throws an [ArgumentError] if the 'description' field is null, as it's a required field.
   @override
   void encode(KeyedArchive object) {
     super.encode(object);

packages/openapi/lib/src/v3/schema.dart

@@ -12,26 +12,129 @@ import 'package:protevus_typeforge/codable.dart';
 import 'package:protevus_openapi/object.dart';
 import 'package:protevus_openapi/v3.dart';
 
+/// Enum representing the policy for additional properties in an API schema.
+///
+/// This enum defines three possible policies for handling additional properties
+/// in an API schema object:
+///
+/// - [disallowed]: Prevents properties other than those defined by [APISchemaObject.properties]
+///   from being included in the schema. This is the most restrictive policy.
+///
+/// - [freeForm]: Allows any additional properties to be included in the schema.
+///   This is the most permissive policy.
+///
+/// - [restricted]: Indicates that [APISchemaObject.additionalPropertySchema] contains
+///   a schema object that defines the structure for any additional properties.
+///   This policy allows additional properties, but they must conform to the
+///   specified schema.
+///
+/// These policies provide different levels of control over the structure and
+/// content of API schemas, allowing for flexible schema definitions based on
+/// specific requirements.
 enum APISchemaAdditionalPropertyPolicy {
-  /// When [APISchemaObject] prevents properties other than those defined by [APISchemaObject.properties] from being included
+  /// Indicates that the [APISchemaObject] prevents properties other than those defined by [APISchemaObject.properties] from being included.
+  ///
+  /// This policy is the most restrictive, disallowing any additional properties beyond those explicitly defined in the schema.
+  /// It ensures that the object structure strictly adheres to the specified properties.
   disallowed,
 
-  /// When [APISchemaObject] allows any additional properties
+  /// Indicates that the [APISchemaObject] allows any additional properties to be included.
+  ///
+  /// This policy is the most permissive, allowing any extra properties beyond those explicitly defined in the schema.
+  /// It provides flexibility for including arbitrary additional data in the object structure.
   freeForm,
 
-  /// When [APISchemaObject.additionalPropertySchema] contains a schema object
+  /// Indicates that [APISchemaObject.additionalPropertySchema] contains a schema object that defines
+  /// the structure for any additional properties.
+  ///
+  /// This policy allows additional properties, but they must conform to the schema specified in
+  /// [APISchemaObject.additionalPropertySchema]. It provides a way to allow extra properties while
+  /// still maintaining some control over their structure and content.
   restricted
 }
 
-/// Represents a schema object in the OpenAPI specification.
+/// This class extends [APIObject] and provides a comprehensive representation of
+/// schema objects as defined in the OpenAPI specification. It includes properties
+/// for various schema constraints such as type, format, range limitations,
+/// length restrictions, pattern matching, and more.
+///
+/// The class offers multiple constructors for creating different types of schemas:
+/// - Default constructor
+/// - Empty constructor
+/// - String schema (with optional format)
+/// - Number schema
+/// - Integer schema
+/// - Boolean schema
+/// - Map schema (with options for additional properties)
+/// - Array schema
+/// - Object schema (with properties)
+/// - File schema
+/// - Free-form schema
+///
+/// It also includes methods for encoding and decoding schema objects to and from
+/// a [KeyedArchive], allowing for serialization and deserialization of schema definitions.
 class APISchemaObject extends APIObject {
+  /// Default constructor for APISchemaObject.
+  ///
+  /// Creates a new instance of APISchemaObject with default values.
+  /// This constructor allows for flexible initialization of the schema object,
+  /// where properties can be set after instantiation.
   APISchemaObject();
+
+  /// Creates an empty [APISchemaObject] instance.
+  ///
+  /// This constructor initializes an [APISchemaObject] without setting any specific properties.
+  /// It can be used as a starting point for building a schema object, where properties
+  /// can be added or modified after instantiation.
   APISchemaObject.empty();
 
+  /// Creates a string [APISchemaObject] instance.
+  ///
+  /// This constructor initializes an [APISchemaObject] with [type] set to [APIType.string].
+  /// It also allows specifying an optional [format] for the string schema.
+  ///
+  /// Parameters:
+  ///   [format]: An optional string that specifies the format of the string schema.
+  ///             Common formats include 'date-time', 'email', 'hostname', etc.
   APISchemaObject.string({this.format}) : type = APIType.string;
+
+  /// Creates a number [APISchemaObject] instance.
+  ///
+  /// This constructor initializes an [APISchemaObject] with [type] set to [APIType.number].
+  /// It's used to define a schema for numeric values, which can include both integers and floating-point numbers.
   APISchemaObject.number() : type = APIType.number;
+
+  /// Creates an integer [APISchemaObject] instance.
+  ///
+  /// This constructor initializes an [APISchemaObject] with [type] set to [APIType.integer].
+  /// It's used to define a schema for integer values, which are whole numbers without fractional components.
   APISchemaObject.integer() : type = APIType.integer;
+
+  /// Creates a boolean [APISchemaObject] instance.
+  ///
+  /// This constructor initializes an [APISchemaObject] with [type] set to [APIType.boolean].
+  /// It's used to define a schema for boolean values, which can only be true or false.
   APISchemaObject.boolean() : type = APIType.boolean;
+
+  /// Creates a map [APISchemaObject] instance.
+  ///
+  /// This constructor initializes an [APISchemaObject] with [type] set to [APIType.object],
+  /// representing a map-like structure. It allows specifying the type or schema of the
+  /// additional properties in the map.
+  ///
+  /// Parameters:
+  ///   [ofType]: An optional [APIType] that specifies the type of values in the map.
+  ///   [ofSchema]: An optional [APISchemaObject] that defines the schema for values in the map.
+  ///   [any]: A boolean flag that, when true, allows any type of additional properties.
+  ///
+  /// Throws:
+  ///   [ArgumentError] if neither [ofType], [ofSchema], nor [any] is specified.
+  ///
+  /// The constructor sets [additionalPropertySchema] based on the provided parameters:
+  /// - If [ofType] is provided, it creates a new [APISchemaObject] with that type.
+  /// - If [ofSchema] is provided, it uses that schema directly.
+  /// - If [any] is true, it allows any additional properties without restrictions.
+  /// - If none of the above are specified, it throws an [ArgumentError].
   APISchemaObject.map({
     APIType? ofType,
     APISchemaObject? ofSchema,
@@ -48,6 +151,23 @@ class APISchemaObject extends APIObject {
       );
     }
   }
+
+  /// Creates an array [APISchemaObject] instance.
+  ///
+  /// This constructor initializes an [APISchemaObject] with [type] set to [APIType.array].
+  /// It allows specifying the type or schema of the items in the array.
+  ///
+  /// Parameters:
+  ///   [ofType]: An optional [APIType] that specifies the type of items in the array.
+  ///   [ofSchema]: An optional [APISchemaObject] that defines the schema for items in the array.
+  ///
+  /// Throws:
+  ///   [ArgumentError] if neither [ofType] nor [ofSchema] is specified.
+  ///
+  /// The constructor sets [items] based on the provided parameters:
+  /// - If [ofType] is provided, it creates a new [APISchemaObject] with that type.
+  /// - If [ofSchema] is provided, it uses that schema directly.
+  /// - If neither is specified, it throws an [ArgumentError].
   APISchemaObject.array({APIType? ofType, APISchemaObject? ofSchema})
       : type = APIType.array {
     if (ofType != null) {
@@ -60,20 +180,54 @@ class APISchemaObject extends APIObject {
       );
     }
   }
+
+  /// Creates an object [APISchemaObject] instance.
+  ///
+  /// This constructor initializes an [APISchemaObject] with [type] set to [APIType.object].
+  /// It allows specifying the properties of the object schema.
+  ///
+  /// Parameters:
+  ///   [properties]: A map of property names to their corresponding [APISchemaObject]s.
+  ///                 This defines the structure of the object schema.
   APISchemaObject.object(this.properties) : type = APIType.object;
+
+  /// Creates a file [APISchemaObject] instance.
+  ///
+  /// This constructor initializes an [APISchemaObject] with [type] set to [APIType.string]
+  /// and [format] set based on the [isBase64Encoded] parameter.
+  ///
+  /// Parameters:
+  ///   [isBase64Encoded]: A boolean flag that determines the format of the file schema.
+  ///     - If true, sets the format to "byte" (for base64-encoded strings).
+  ///     - If false, sets the format to "binary" (for raw binary data).
+  ///
+  /// The resulting schema object represents either a base64-encoded string (when [isBase64Encoded] is true)
+  /// or raw binary data (when [isBase64Encoded] is false), both of which are suitable for file content.
   APISchemaObject.file({bool isBase64Encoded = false})
       : type = APIType.string,
         format = isBase64Encoded ? "byte" : "binary";
 
+  /// Creates a free-form [APISchemaObject] instance.
+  ///
+  /// This constructor initializes an [APISchemaObject] with [type] set to [APIType.object]
+  /// and [additionalPropertyPolicy] set to [APISchemaAdditionalPropertyPolicy.freeForm].
+  /// It represents a schema that allows any additional properties without restrictions.
+  ///
+  /// This is useful for scenarios where the object structure is not strictly defined
+  /// and can contain arbitrary key-value pairs.
   APISchemaObject.freeForm()
       : type = APIType.object,
         additionalPropertyPolicy = APISchemaAdditionalPropertyPolicy.freeForm;
 
   /// A title for the object.
+  ///
+  /// This property allows you to specify a human-readable title for the schema object.
+  /// It can be used to provide a brief, descriptive name for the schema, which can be
+  /// helpful for documentation and user interfaces. The title is optional and does not
+  /// affect the validation of data against the schema.
   String? title;
 
-  /// The value of "maximum" MUST be a number, representing an upper limit
-  /// for a numeric instance.
+  /// The maximum value for a numeric instance.
   ///
   /// If the instance is a number, then this keyword validates if
   /// "exclusiveMaximum" is true and instance is less than the provided
@@ -81,8 +235,7 @@ class APISchemaObject extends APIObject {
   /// provided value.
   num? maximum;
 
-  ///  The value of "exclusiveMaximum" MUST be a boolean, representing
-  ///  whether the limit in "maximum" is exclusive or not.
+  /// Determines whether the maximum value is exclusive.
   ///
   ///  An undefined value is the same as false.
   ///
@@ -92,26 +245,31 @@ class APISchemaObject extends APIObject {
   ///  value of "maximum".
   bool? exclusiveMaximum;
 
-  /// The value of "minimum" MUST be a number, representing a lower limit
-  /// for a numeric instance.
-
-  /// If the instance is a number, then this keyword validates if
-  /// "exclusiveMinimum" is true and instance is greater than the provided
-  /// value, or else if the instance is greater than or exactly equal to
-  /// the provided value.
+  /// The minimum value for a numeric instance.
+  ///
+  /// This property sets the lower limit for a numeric instance in the schema.
+  /// The value of "minimum" MUST be a number.
+  ///
+  /// If the instance is a number, this keyword validates in two ways:
+  /// 1. If "exclusiveMinimum" is true, the instance must be greater than the provided value.
+  /// 2. If "exclusiveMinimum" is false or not specified, the instance must be greater than or exactly equal to the provided value.
+  ///
+  /// This property works in conjunction with [exclusiveMinimum] to define the lower bound behavior.
   num? minimum;
 
+  /// Determines whether the minimum value is exclusive.
+  ///
   /// The value of "exclusiveMinimum" MUST be a boolean, representing
   /// whether the limit in "minimum" is exclusive or not.  An undefined
   /// value is the same as false.
-
+  ///
   /// If "exclusiveMinimum" is true, then a numeric instance SHOULD NOT be
   /// equal to the value specified in "minimum".  If "exclusiveMinimum" is
   /// false (or not specified), then a numeric instance MAY be equal to the
   /// value of "minimum".
   bool? exclusiveMinimum;
 
-  /// The value of this keyword MUST be a non-negative integer.
+  /// The maximum length allowed for a string instance.
   ///
   /// The value of this keyword MUST be an integer.  This integer MUST be
   /// greater than, or equal to, 0.
@@ -123,8 +281,7 @@ class APISchemaObject extends APIObject {
   /// characters as defined by RFC 7159 [RFC7159].
   int? maxLength;
 
-  /// A string instance is valid against this keyword if its length is
-  /// greater than, or equal to, the value of this keyword.
+  /// The minimum length allowed for a string instance.
   ///
   /// The length of a string instance is defined as the number of its
   /// characters as defined by RFC 7159 [RFC7159].
@@ -136,24 +293,20 @@ class APISchemaObject extends APIObject {
   /// integer value 0.
   int? minLength;
 
-  /// The value of this keyword MUST be a string.  This string SHOULD be a
-  /// valid regular expression, according to the ECMA 262 regular
-  /// expression dialect.
+  /// The regular expression pattern that a string instance must match.
   ///
   /// A string instance is considered valid if the regular expression
   /// matches the instance successfully.  Recall: regular expressions are
   /// not implicitly anchored.
   String? pattern;
 
-  /// The value of this keyword MUST be an integer.  This integer MUST be
-  /// greater than, or equal to, 0.
+  /// The maximum number of items allowed in an array instance.
   ///
   /// An array instance is valid against "maxItems" if its size is less
   /// than, or equal to, the value of this keyword.
   int? maxItems;
 
-  /// The value of this keyword MUST be an integer.  This integer MUST be
-  /// greater than, or equal to, 0.
+  /// The minimum number of items allowed in an array instance.
   ///
   /// An array instance is valid against "minItems" if its size is greater
   /// than, or equal to, the value of this keyword.
@@ -162,31 +315,31 @@ class APISchemaObject extends APIObject {
   /// value of 0.
   int? minItems;
 
-  /// The value of this keyword MUST be a boolean.
+  /// Specifies whether the items in an array instance must be unique.
   ///
   /// If this keyword has boolean value false, the instance validates
   /// successfully.  If it has boolean value true, the instance validates
   /// successfully if all of its elements are unique.
-
+  ///
   /// If not present, this keyword may be considered present with boolean
   /// value false.
   bool? uniqueItems;
 
+  /// Specifies a value that numeric instances must be divisible by.
+  ///
   /// The value of "multipleOf" MUST be a number, strictly greater than 0.
-
+  ///
   /// A numeric instance is only valid if division by this keyword's value
   /// results in an integer.
   num? multipleOf;
 
-  /// The value of this keyword MUST be an integer.  This integer MUST be
-  /// greater than, or equal to, 0.
+  /// The maximum number of properties allowed in an object instance.
   ///
   /// An object instance is valid against "maxProperties" if its number of
   /// properties is less than, or equal to, the value of this keyword.
   int? maxProperties;
 
-  /// The value of this keyword MUST be an integer.  This integer MUST be
-  /// greater than, or equal to, 0.
+  /// The minimum number of properties allowed in an object instance.
   ///
   /// An object instance is valid against "minProperties" if its number of
   /// properties is greater than, or equal to, the value of this keyword.
@@ -195,16 +348,13 @@ class APISchemaObject extends APIObject {
   /// value of 0.
   int? minProperties;
 
-  /// The value of this keyword MUST be an array.  This array MUST have at
-  /// least one element.  Elements of this array MUST be strings, and MUST
-  /// be unique.
+  /// A list of required property names for the schema object.
   ///
   /// An object instance is valid against this keyword if its property set
   /// contains all elements in this keyword's array value.
   List<String?>? isRequired;
 
-  /// The value of this keyword MUST be an array.  This array SHOULD have
-  /// at least one element.  Elements in the array SHOULD be unique.
+  /// Specifies a list of allowed values for the schema instance.
   ///
   /// Elements in the array MAY be of any type, including null.
   ///
@@ -214,50 +364,288 @@ class APISchemaObject extends APIObject {
 
   /* Modified JSON Schema for OpenAPI */
 
+  /// Represents the type of the API schema object.
+  ///
+  /// This property defines the data type of the schema. It can be any of the
+  /// values defined in the [APIType] enum, such as string, number, integer,
+  /// boolean, array, or object.
+  ///
+  /// The type is a fundamental property of the schema as it determines the
+  /// basic structure and validation rules for the data that the schema represents.
+  ///
+  /// If null, it indicates that the type is not specified, which might be the case
+  /// for schemas that use composition keywords like allOf, anyOf, or oneOf.
   APIType? type;
+
+  /// A list of schema objects that this schema object composes.
+  ///
+  /// This property allows for the composition of schema objects through the 'allOf' keyword.
+  /// The instance data must be valid against all of the schemas in this list.
+  /// This is ANDing the constraints specified by each schema in the list.
+  ///
+  /// If null, it indicates that no composition is specified for this schema object.
   List<APISchemaObject?>? allOf;
+
+  /// A list of schema objects that this schema object can be any of.
+  ///
+  /// This property allows for the composition of schema objects through the 'anyOf' keyword.
+  /// The instance data must be valid against at least one of the schemas in this list.
+  /// This is ORing the constraints specified by each schema in the list.
+  ///
+  /// If null, it indicates that no 'anyOf' composition is specified for this schema object.
   List<APISchemaObject?>? anyOf;
+
+  /// A list of schema objects that this schema object can be one of.
+  ///
+  /// This property allows for the composition of schema objects through the 'oneOf' keyword.
+  /// The instance data must be valid against exactly one of the schemas in this list.
+  /// This represents an exclusive OR (XOR) relationship between the schemas.
+  ///
+  /// If null, it indicates that no 'oneOf' composition is specified for this schema object.
   List<APISchemaObject?>? oneOf;
+
+  /// A schema object that this schema object must not match.
+  ///
+  /// This property allows for the negation of a schema through the 'not' keyword.
+  /// The instance data must NOT be valid against the schema defined in this property.
+  /// This is useful for expressing constraints that are the opposite of a given schema.
+  ///
+  /// If null, it indicates that no 'not' constraint is specified for this schema object.
   APISchemaObject? not;
 
+  /// Defines the schema for items in an array.
+  ///
+  /// This property is only applicable when the [type] is set to [APIType.array].
+  /// It specifies the schema that all items in the array must conform to.
+  ///
+  /// If null, it indicates that the schema for array items is not specified,
+  /// allowing items of any type in the array.
   APISchemaObject? items;
+
+  /// A map of property names to their corresponding schema objects.
+  ///
+  /// This property defines the structure of an object schema by specifying
+  /// the schemas for its properties. Each key in the map is the name of a
+  /// property, and its corresponding value is an [APISchemaObject] that
+  /// defines the schema for that property.
+  ///
+  /// If null, it indicates that no properties are defined for this schema object.
+  /// This could be the case for non-object schemas or for object schemas where
+  /// properties are not explicitly defined (e.g., when using additionalProperties).
   Map<String, APISchemaObject?>? properties;
+
+  /// Defines the schema for additional properties in an object.
+  ///
+  /// This property is used in conjunction with [additionalPropertyPolicy] to specify
+  /// the schema for additional properties when [additionalPropertyPolicy] is set to
+  /// [APISchemaAdditionalPropertyPolicy.restricted].
+  ///
+  /// If null, it indicates that no specific schema is defined for additional properties,
+  /// which could mean either that additional properties are not allowed or that they
+  /// can be of any type, depending on the [additionalPropertyPolicy].
   APISchemaObject? additionalPropertySchema;
+
+  /// Specifies the policy for handling additional properties in the schema object.
+  ///
+  /// This property determines how the schema should treat properties that are not
+  /// explicitly defined in the [properties] map. It can have one of three values:
+  ///
+  /// - [APISchemaAdditionalPropertyPolicy.disallowed]: No additional properties are allowed.
+  /// - [APISchemaAdditionalPropertyPolicy.freeForm]: Any additional properties are allowed without restrictions.
+  /// - [APISchemaAdditionalPropertyPolicy.restricted]: Additional properties are allowed, but must conform to the schema defined in [additionalPropertySchema].
+  ///
+  /// If null, the additional property policy is not explicitly set, and the behavior
+  /// may depend on the context or default to a specific policy (often 'disallowed' in strict schemas).
   APISchemaAdditionalPropertyPolicy? additionalPropertyPolicy;
 
+  /// A description of the schema object.
+  ///
+  /// This property provides a detailed explanation of the purpose, structure,
+  /// or constraints of the schema. It can be used to give more context to API
+  /// consumers about what this schema represents or how it should be used.
+  ///
+  /// If null, it indicates that no description has been provided for this schema.
   String? description;
+
+  /// Specifies the format of the data.
+  ///
+  /// This property is a string that further defines the specific format of the data
+  /// described by the schema. It is often used in conjunction with the [type] property
+  /// to provide more detailed type information.
+  ///
+  /// Common formats include:
+  /// - For strings: 'date-time', 'date', 'email', 'hostname', 'ipv4', 'ipv6', 'uri', etc.
+  /// - For numbers: 'float', 'double'
+  /// - For integers: 'int32', 'int64'
+  ///
+  /// The interpretation and validation of the format may depend on the data type
+  /// and the specific OpenAPI tooling being used.
+  ///
+  /// If null, it indicates that no specific format is defined for this schema property.
   String? format;
+
+  /// The default value for this schema object.
+  ///
+  /// This property specifies the default value to be used if the instance value is not supplied.
+  /// The value SHOULD be valid against the schema.
+  ///
+  /// The type of this property is dynamic, allowing for default values of any type
+  /// that matches the schema's type. For example:
+  /// - For string schemas, it could be a String.
+  /// - For number schemas, it could be a num.
+  /// - For boolean schemas, it could be a bool.
+  /// - For array schemas, it could be a List.
+  /// - For object schemas, it could be a Map.
+  ///
+  /// If null, it indicates that no default value is specified for this schema property.
   dynamic defaultValue;
 
+  /// Determines whether the schema allows null values.
+  ///
+  /// This getter returns a boolean value indicating if the schema permits null values.
+  /// It returns true if the schema explicitly allows null values, and false otherwise.
+  ///
+  /// The getter uses the nullish coalescing operator (??) to provide a default value of false
+  /// if the internal [_nullable] property is null.
+  ///
+  /// Returns:
+  ///   A boolean value: true if the schema allows null values, false otherwise.
   bool? get isNullable => _nullable ?? false;
 
+  /// Sets whether the schema allows null values.
+  ///
+  /// This setter allows you to specify if the schema should permit null values.
+  /// Setting it to true means the schema will allow null, while false means it won't.
+  ///
+  /// Parameters:
+  ///   [n]: A boolean value indicating whether null is allowed (true) or not (false).
+  ///        Can be null, in which case it will clear any previously set value.
   set isNullable(bool? n) {
     _nullable = n;
   }
 
   // APIDiscriminator discriminator;
 
+  /// Determines whether the schema is read-only.
+  ///
+  /// This getter returns a boolean value indicating if the schema is marked as read-only.
+  /// It returns true if the schema is explicitly set as read-only, and false otherwise.
+  ///
+  /// The getter uses the nullish coalescing operator (??) to provide a default value of false
+  /// if the internal [_readOnly] property is null.
+  ///
+  /// Returns:
+  ///   A boolean value: true if the schema is read-only, false otherwise.
   bool? get isReadOnly => _readOnly ?? false;
 
+  /// Sets whether the schema is read-only.
+  ///
+  /// This setter allows you to specify if the schema should be considered read-only.
+  /// Setting it to true means the schema is read-only, while false means it's not.
+  ///
+  /// Parameters:
+  ///   [n]: A boolean value indicating whether the schema is read-only (true) or not (false).
+  ///        Can be null, in which case it will clear any previously set value.
   set isReadOnly(bool? n) {
     _readOnly = n;
   }
 
+  /// Determines whether the schema is write-only.
+  ///
+  /// This getter returns a boolean value indicating if the schema is marked as write-only.
+  /// It returns true if the schema is explicitly set as write-only, and false otherwise.
+  ///
+  /// The getter uses the nullish coalescing operator (??) to provide a default value of false
+  /// if the internal [_writeOnly] property is null.
+  ///
+  /// Returns:
+  ///   A boolean value: true if the schema is write-only, false otherwise.
   bool? get isWriteOnly => _writeOnly ?? false;
 
   set isWriteOnly(bool? n) {
     _writeOnly = n;
   }
 
+  /// Internal boolean flag to determine if the schema allows null values.
+  ///
+  /// This private property is used to store the nullable state of the schema.
+  /// It's accessed and modified through the public [isNullable] getter and setter.
+  ///
+  /// - If true, the schema allows null values.
+  /// - If false, the schema does not allow null values.
+  /// - If null, the nullable state is not explicitly set, defaulting to false in the getter.
   bool? _nullable;
+
+  /// Internal boolean flag to determine if the schema is read-only.
+  ///
+  /// This private property is used to store the read-only state of the schema.
+  /// It's accessed and modified through the public [isReadOnly] getter and setter.
+  ///
+  /// - If true, the schema is read-only.
+  /// - If false, the schema is not read-only.
+  /// - If null, the read-only state is not explicitly set, defaulting to false in the getter.
   bool? _readOnly;
+
+  /// Internal boolean flag to determine if the schema is write-only.
+  ///
+  /// This private property is used to store the write-only state of the schema.
+  /// It's accessed and modified through the public [isWriteOnly] getter and setter.
+  ///
+  /// - If true, the schema is write-only.
+  /// - If false, the schema is not write-only.
+  /// - If null, the write-only state is not explicitly set, defaulting to false in the getter.
   bool? _writeOnly;
+
+  /// Indicates whether the schema is deprecated.
+  ///
+  /// This property specifies if the schema has been deprecated and should be avoided in new implementations.
+  ///
+  /// - If true, the schema is considered deprecated.
+  /// - If false, the schema is not deprecated.
+  /// - If null, the deprecation status is not explicitly set.
+  ///
+  /// Deprecated schemas may still be used but are typically discouraged in favor of newer alternatives.
   bool? deprecated;
 
+  /// Provides a map of property names to their corresponding cast functions.
+  ///
+  /// This getter overrides the base implementation to specify custom casting
+  /// behavior for certain properties of the APISchemaObject.
+  ///
+  /// Returns:
+  ///   A Map<String, cast.Cast> where:
+  ///   - The key "required" is associated with a cast.List(cast.string) function,
+  ///     which casts the "required" property to a List of Strings.
+  ///
+  /// This ensures that when decoding JSON data, the "required" field is properly
+  /// cast to a List<String>, maintaining type safety and consistency in the object model.
   @override
   Map<String, cast.Cast> get castMap =>
       {"required": const cast.List(cast.string)};
 
+  /// Decodes a [KeyedArchive] object into this [APISchemaObject] instance.
+  ///
+  /// This method populates the properties of the [APISchemaObject] by extracting
+  /// values from the provided [KeyedArchive] object. It handles both simple properties
+  /// and complex nested structures.
+  ///
+  /// The method decodes various schema properties including:
+  /// - Basic properties like title, maximum, minimum, pattern, etc.
+  /// - Numeric constraints (maxLength, minLength, maxItems, minItems, etc.)
+  /// - Enumerated values and required fields
+  /// - Complex structures like allOf, anyOf, oneOf, and nested schemas
+  /// - Additional properties policy and schema
+  /// - Metadata like description, format, and default value
+  ///
+  /// It also handles special cases like the 'additionalProperties' field, which
+  /// can be a boolean or an object, affecting the [additionalPropertyPolicy] and
+  /// [additionalPropertySchema] properties.
+  ///
+  /// Parameters:
+  ///   [object]: A [KeyedArchive] containing the encoded schema data.
+  ///
+  /// Note: This method overrides the [decode] method from a superclass and
+  /// calls the superclass implementation before proceeding with its own decoding.
   @override
   void decode(KeyedArchive object) {
     super.decode(object);
@@ -315,6 +703,28 @@ class APISchemaObject extends APIObject {
     deprecated = object.decode("deprecated");
   }
 
+  /// Encodes this [APISchemaObject] instance into a [KeyedArchive] object.
+  ///
+  /// This method serializes all properties of the [APISchemaObject] into the provided
+  /// [KeyedArchive] object. It handles both simple properties and complex nested structures.
+  ///
+  /// The method encodes various schema properties including:
+  /// - Basic properties like title, maximum, minimum, pattern, etc.
+  /// - Numeric constraints (maxLength, minLength, maxItems, minItems, etc.)
+  /// - Enumerated values and required fields
+  /// - Complex structures like allOf, anyOf, oneOf, and nested schemas
+  /// - Additional properties policy and schema
+  /// - Metadata like description, format, and default value
+  ///
+  /// It also handles special cases like the 'additionalProperties' field, which
+  /// is encoded differently based on the [additionalPropertyPolicy] and
+  /// [additionalPropertySchema] properties.
+  ///
+  /// Parameters:
+  ///   [object]: A [KeyedArchive] to store the encoded schema data.
+  ///
+  /// Note: This method overrides the [encode] method from a superclass and
+  /// calls the superclass implementation before proceeding with its own encoding.
   @override
   void encode(KeyedArchive object) {
     super.encode(object);

packages/openapi/lib/src/v3/security.dart

@@ -11,9 +11,30 @@ import 'package:protevus_typeforge/codable.dart';
 import 'package:protevus_openapi/object.dart';
 import 'package:protevus_openapi/v3.dart';
 
+/// Represents the different types of security schemes available in the OpenAPI specification.
+///
+/// - [apiKey]: API key-based security scheme.
+/// - [http]: HTTP authentication scheme.
+/// - [oauth2]: OAuth 2.0 authentication scheme.
+/// - [openID]: OpenID Connect authentication scheme.
 enum APISecuritySchemeType { apiKey, http, oauth2, openID }
 
+/// A utility class for encoding and decoding [APISecuritySchemeType] values.
+///
+/// This class provides static methods to convert between [APISecuritySchemeType] enum values
+/// and their corresponding string representations as defined in the OpenAPI specification.
 class APISecuritySchemeTypeCodec {
+  /// Decodes a string representation of an API security scheme type into an [APISecuritySchemeType] enum value.
+  ///
+  /// This method takes a [String] parameter `type` and returns the corresponding
+  /// [APISecuritySchemeType] enum value. If the input string doesn't match any
+  /// known security scheme type, the method returns `null`.
+  ///
+  /// Parameters:
+  ///   - type: A [String] representing the security scheme type.
+  ///
+  /// Returns:
+  ///   The corresponding [APISecuritySchemeType] enum value, or `null` if no match is found.
   static APISecuritySchemeType? decode(String? type) {
     switch (type) {
       case "apiKey":
@@ -29,6 +50,17 @@ class APISecuritySchemeTypeCodec {
     }
   }
 
+  /// Encodes an [APISecuritySchemeType] enum value into its corresponding string representation.
+  ///
+  /// This method takes an [APISecuritySchemeType] parameter `type` and returns the corresponding
+  /// string representation as defined in the OpenAPI specification. If the input is `null` or
+  /// doesn't match any known security scheme type, the method returns `null`.
+  ///
+  /// Parameters:
+  ///   - type: An [APISecuritySchemeType] enum value to be encoded.
+  ///
+  /// Returns:
+  ///   A [String] representing the security scheme type, or `null` if the input is `null` or invalid.
   static String? encode(APISecuritySchemeType? type) {
     switch (type) {
       case APISecuritySchemeType.apiKey:
@@ -47,55 +79,183 @@ class APISecuritySchemeTypeCodec {
 
 /// Defines a security scheme that can be used by the operations.
 ///
-/// Supported schemes are HTTP authentication, an API key (either as a header or as a query parameter), OAuth2's common flows (implicit, password, application and access code) as defined in RFC6749, and OpenID Connect Discovery.
+/// Supported schemes are HTTP authentication, an API key (either as a header or as a query parameter),
+/// OAuth2's common flows (implicit, password, application and access code) as defined in RFC6749,
+/// and OpenID Connect Discovery.
+///
+/// This class represents different types of security schemes:
+/// - HTTP authentication (using [APISecurityScheme.http])
+/// - API Key (using [APISecurityScheme.apiKey])
+/// - OAuth2 (using [APISecurityScheme.oauth2])
+/// - OpenID Connect (using [APISecurityScheme.openID])
+///
+/// The [type] property determines which security scheme is being used, and the corresponding
+/// properties should be set based on the chosen type.
+///
+/// When encoding or decoding, the class ensures that the required properties for each type
+/// are present and correctly formatted.
 class APISecurityScheme extends APIObject {
+  /// Default constructor for APISecurityScheme.
+  ///
+  /// Creates an instance of APISecurityScheme with no initial values set.
+  /// Use this constructor when you need to create an empty security scheme
+  /// that will be populated later or when you want to manually set all properties.
   APISecurityScheme();
+
+  /// Creates an empty instance of APISecurityScheme.
+  ///
+  /// This named constructor initializes an APISecurityScheme with no pre-set values.
+  /// It can be used when you need to create a security scheme object that will be
+  /// populated with data later or when you want to manually set all properties.
   APISecurityScheme.empty();
 
+  /// Creates an instance of APISecurityScheme for HTTP authentication.
+  ///
+  /// This constructor initializes a security scheme of type [APISecuritySchemeType.http]
+  /// with the specified [scheme].
+  ///
+  /// Parameters:
+  ///   - scheme: A [String] representing the name of the HTTP Authorization scheme
+  ///     to be used in the Authorization header as defined in RFC7235.
+  ///
+  /// Example:
+  ///   ```dart
+  ///   var httpScheme = APISecurityScheme.http('bearer');
+  ///   ```
   APISecurityScheme.http(this.scheme) : type = APISecuritySchemeType.http;
 
+  /// Creates an instance of APISecurityScheme for API Key authentication.
+  ///
+  /// This constructor initializes a security scheme of type [APISecuritySchemeType.apiKey]
+  /// with the specified [name] and [location].
+  ///
+  /// Parameters:
+  ///   - name: A [String] representing the name of the API key to be used.
+  ///   - location: An [APIParameterLocation] specifying where the API key is expected
+  ///     (e.g., query parameter, header, or cookie).
+  ///
+  /// Example:
+  ///   ```dart
+  ///   var apiKeyScheme = APISecurityScheme.apiKey('api_key', APIParameterLocation.header);
+  ///   ```
   APISecurityScheme.apiKey(this.name, this.location)
       : type = APISecuritySchemeType.apiKey;
 
+  /// Creates an instance of APISecurityScheme for OAuth2 authentication.
+  ///
+  /// This constructor initializes a security scheme of type [APISecuritySchemeType.oauth2]
+  /// with the specified [flows].
+  ///
+  /// Parameters:
+  ///   - flows: A [Map<String, APISecuritySchemeOAuth2Flow?>] representing the OAuth2 flows
+  ///     supported by this security scheme. The keys should be flow types
+  ///     (e.g., "implicit", "authorizationCode", "clientCredentials", "password"),
+  ///     and the values should be instances of [APISecuritySchemeOAuth2Flow].
+  ///
+  /// Example:
+  ///   ```dart
+  ///   var oauth2Scheme = APISecurityScheme.oauth2({
+  ///     'implicit': APISecuritySchemeOAuth2Flow.implicit(
+  ///       Uri.parse('https://example.com/oauth/authorize'),
+  ///       Uri.parse('https://example.com/oauth/token'),
+  ///       {'read:api': 'Read access to protected resources'},
+  ///     ),
+  ///   });
+  ///   ```
   APISecurityScheme.oauth2(this.flows) : type = APISecuritySchemeType.oauth2;
 
+  /// Creates an instance of APISecurityScheme for OpenID Connect authentication.
+  ///
+  /// This constructor initializes a security scheme of type [APISecuritySchemeType.openID]
+  /// with the specified [connectURL].
+  ///
+  /// Parameters:
+  ///   - connectURL: A [Uri] representing the OpenID Connect URL used to discover
+  ///     OAuth2 configuration values. This MUST be in the form of a URL.
+  ///
+  /// Example:
+  ///   ```dart
+  ///   var openIDScheme = APISecurityScheme.openID(
+  ///     Uri.parse('https://example.com/.well-known/openid-configuration')
+  ///   );
+  ///   ```
   APISecurityScheme.openID(this.connectURL)
       : type = APISecuritySchemeType.openID;
 
   /// The type of the security scheme.
   ///
-  /// REQUIRED. Valid values are "apiKey", "http", "oauth2", "openIdConnect".
+  /// This property defines the type of security scheme used, which determines
+  /// how the security is enforced and what additional properties are required.
+  ///
+  /// REQUIRED. Valid values are:
+  /// - "apiKey": For API key-based authentication
+  /// - "http": For HTTP authentication schemes
+  /// - "oauth2": For OAuth2 authentication
+  /// - "openIdConnect": For OpenID Connect Discovery-based authentication
+  ///
+  /// The value of this property affects which other properties of the
+  /// [APISecurityScheme] are required or applicable.
   APISecuritySchemeType? type;
 
-  /// A short description for security scheme.
-  /// CommonMark syntax MAY be used for rich text representation.
+  /// A short description for the security scheme.
+  ///
+  /// This property provides a brief explanation of the security scheme's purpose or usage.
+  /// It can be used to give additional context or details about how the security mechanism works.
+  ///
+  /// The description MAY use CommonMark syntax for rich text representation, allowing
+  /// for formatted text, links, and other markdown features to enhance readability.
+  ///
+  /// This field is optional but recommended to improve the documentation of the API's security measures.
   String? description;
 
   /// The name of the header, query or cookie parameter to be used.
   ///
-  /// For apiKey only. REQUIRED if so.
+  /// This property specifies the name of the parameter that will be used to pass the API key.
+  /// It is applicable only when the security scheme type is [APISecuritySchemeType.apiKey].
+  ///
+  /// The value of this property depends on the [location] property:
+  /// - If [location] is [APIParameterLocation.header], this is the name of the header.
+  /// - If [location] is [APIParameterLocation.query], this is the name of the query parameter.
+  /// - If [location] is [APIParameterLocation.cookie], this is the name of the cookie.
+  ///
+  /// This property is REQUIRED when the security scheme type is [APISecuritySchemeType.apiKey].
   String? name;
 
   /// The location of the API key.
   ///
-  /// Valid values are "query", "header" or "cookie".
+  /// This property specifies where the API key should be sent in the request.
+  /// It is only applicable and REQUIRED when the security scheme type is [APISecuritySchemeType.apiKey].
   ///
   /// For apiKey only. REQUIRED if so.
   APIParameterLocation? location;
 
   /// The name of the HTTP Authorization scheme to be used in the Authorization header as defined in RFC7235.
   ///
+  /// This property specifies the name of the HTTP Authorization scheme that will be used
+  /// in the Authorization header for requests. It is only applicable and REQUIRED when
+  /// the security scheme type is [APISecuritySchemeType.http].
+  ///
+  /// Common values include:
+  /// - "basic": for Basic Authentication
+  /// - "bearer": for Bearer Token Authentication
+  /// - "digest": for Digest Access Authentication
+  ///
+  /// The value of this property should correspond to the authentication scheme
+  /// as defined in RFC7235 and should be registered in the IANA Authentication Scheme Registry.
+  ///
   /// For http only. REQUIRED if so.
   String? scheme;
 
   /// A hint to the client to identify how the bearer token is formatted.
   ///
-  /// Bearer tokens are usually generated by an authorization server, so this information is primarily for documentation purposes.
+  /// This property provides additional information about the format of the bearer token
+  /// when using HTTP authentication with a 'bearer' scheme. It is typically used for
+  /// documentation purposes to help API consumers understand the expected token format.
   ///
   /// For http only.
   String? format;
 
-  /// An object containing configuration information for the flow types supported.
+  /// An object containing configuration information for the flow types supported in OAuth2 authentication.
   ///
   /// Fixed keys are implicit, password, clientCredentials and authorizationCode.
   ///
@@ -107,8 +267,46 @@ class APISecurityScheme extends APIObject {
   /// This MUST be in the form of a URL.
   ///
   /// For openID only. REQUIRED if so.
+  ///
+  /// This property specifies the OpenID Connect URL used to discover OAuth2 configuration values.
+  /// It is only applicable and REQUIRED when the security scheme type is [APISecuritySchemeType.openID].
+  ///
+  /// The URL should point to the OpenID Connect discovery endpoint, typically ending with
+  /// '.well-known/openid-configuration'. This endpoint provides information about the OpenID Provider's
+  /// configuration, including the OAuth 2.0 endpoint locations.
+  ///
+  /// Example:
+  ///   ```dart
+  ///   connectURL = Uri.parse('https://example.com/.well-known/openid-configuration');
+  ///   ```
+  ///
+  /// Note: This URL must be a valid URI and should be accessible to clients for retrieving
+  /// the necessary configuration information to initiate the OpenID Connect authentication flow.
   Uri? connectURL;
 
+  /// Decodes the security scheme information from a [KeyedArchive] object.
+  ///
+  /// This method is responsible for populating the properties of the [APISecurityScheme]
+  /// instance based on the data stored in the provided [KeyedArchive] object. It handles
+  /// the decoding process for different security scheme types, including API key, OAuth2,
+  /// HTTP authentication, and OpenID Connect.
+  ///
+  /// The method performs the following steps:
+  /// 1. Calls the superclass's decode method.
+  /// 2. Decodes the 'type' and 'description' fields.
+  /// 3. Based on the security scheme type, decodes additional fields specific to that type:
+  ///    - For API key: decodes 'name' and 'in' (location) fields.
+  ///    - For OAuth2: decodes the 'flows' object.
+  ///    - For HTTP: decodes 'scheme' and 'bearerFormat' fields.
+  ///    - For OpenID Connect: decodes the 'openIdConnectUrl' field.
+  ///
+  /// If the security scheme type is not recognized, it throws an [ArgumentError].
+  ///
+  /// Parameters:
+  ///   - object: A [KeyedArchive] containing the encoded security scheme data.
+  ///
+  /// Throws:
+  ///   - [ArgumentError] if the security scheme type is null or not recognized.
   @override
   void decode(KeyedArchive object) {
     super.decode(object);
@@ -149,6 +347,32 @@ class APISecurityScheme extends APIObject {
     }
   }
 
+  /// Encodes the security scheme information into a [KeyedArchive] object.
+  ///
+  /// This method is responsible for encoding the properties of the [APISecurityScheme]
+  /// instance into the provided [KeyedArchive] object. It handles the encoding process
+  /// for different security scheme types, including API key, OAuth2, HTTP authentication,
+  /// and OpenID Connect.
+  ///
+  /// The method performs the following steps:
+  /// 1. Calls the superclass's encode method.
+  /// 2. Checks if the 'type' property is set, throwing an [ArgumentError] if it's null.
+  /// 3. Encodes the 'type' and 'description' fields.
+  /// 4. Based on the security scheme type, encodes additional fields specific to that type:
+  ///    - For API key: encodes 'name' and 'in' (location) fields.
+  ///    - For OAuth2: encodes the 'flows' object.
+  ///    - For HTTP: encodes 'scheme' and 'bearerFormat' fields.
+  ///    - For OpenID Connect: encodes the 'openIdConnectUrl' field.
+  ///
+  /// For each type, it checks if the required properties are non-null and throws
+  /// an [ArgumentError] if any required property is missing.
+  ///
+  /// Parameters:
+  ///   - object: A [KeyedArchive] to store the encoded security scheme data.
+  ///
+  /// Throws:
+  ///   - [ArgumentError] if the security scheme type is null or if any required
+  ///     property for a specific type is missing.
   @override
   void encode(KeyedArchive object) {
     super.encode(object);
@@ -216,25 +440,132 @@ class APISecurityScheme extends APIObject {
   }
 }
 
-/// Allows configuration of the supported OAuth Flows.
+/// This class represents the configuration for different OAuth 2.0 flows as defined in the OpenAPI specification.
+/// It supports the following OAuth 2.0 flows:
+/// - Authorization Code
+/// - Implicit
+/// - Resource Owner Password Credentials
+/// - Client Credentials
+///
+/// Each flow type has its own constructor with the required parameters:
+/// - [APISecuritySchemeOAuth2Flow.code]: For Authorization Code flow
+/// - [APISecuritySchemeOAuth2Flow.implicit]: For Implicit flow
+/// - [APISecuritySchemeOAuth2Flow.password]: For Resource Owner Password Credentials flow
+/// - [APISecuritySchemeOAuth2Flow.client]: For Client Credentials flow
+///
+/// The class provides properties for configuring the OAuth 2.0 endpoints and available scopes:
+/// - [authorizationURL]: The authorization endpoint URL (required for Authorization Code and Implicit flows)
+/// - [tokenURL]: The token endpoint URL (required for Authorization Code, Password, and Client Credentials flows)
+/// - [refreshURL]: The refresh token endpoint URL (optional)
+/// - [scopes]: A map of available scopes and their descriptions (required for all flows)
+///
+/// This class extends [APIObject] and provides methods for encoding and decoding its properties
+/// to and from a [KeyedArchive] object, which is used for serialization and deserialization.
 class APISecuritySchemeOAuth2Flow extends APIObject {
+  /// Creates an empty instance of APISecuritySchemeOAuth2Flow.
+  ///
+  /// This constructor initializes an APISecuritySchemeOAuth2Flow with no pre-set values.
+  /// It can be used when you need to create an OAuth2 flow object that will be
+  /// populated with data later or when you want to manually set all properties.
   APISecuritySchemeOAuth2Flow.empty();
+
+  /// Creates an instance of APISecuritySchemeOAuth2Flow for the Authorization Code flow.
+  ///
+  /// This constructor initializes an OAuth2 flow configuration for the Authorization Code grant type.
+  ///
+  /// Parameters:
+  ///   - authorizationURL: The authorization endpoint URL. REQUIRED.
+  ///   - tokenURL: The token endpoint URL. REQUIRED.
+  ///   - refreshURL: The refresh token endpoint URL. Optional.
+  ///   - scopes: A map of available scopes and their descriptions. REQUIRED.
+  ///
+  /// All URL parameters should be in the form of a valid URL.
+  ///
+  /// Example:
+  ///   ```dart
+  ///   var codeFlow = APISecuritySchemeOAuth2Flow.code(
+  ///     Uri.parse('https://example.com/oauth/authorize'),
+  ///     Uri.parse('https://example.com/oauth/token'),
+  ///     Uri.parse('https://example.com/oauth/refresh'),
+  ///     {'read:api': 'Read access to protected resources'},
+  ///   );
+  ///   ```
   APISecuritySchemeOAuth2Flow.code(
     this.authorizationURL,
     this.tokenURL,
     this.refreshURL,
     this.scopes,
   );
+
+  /// Creates an instance of APISecuritySchemeOAuth2Flow for the Implicit flow.
+  ///
+  /// This constructor initializes an OAuth2 flow configuration for the Implicit grant type.
+  ///
+  /// Parameters:
+  ///   - authorizationURL: The authorization endpoint URL. REQUIRED.
+  ///   - refreshURL: The refresh token endpoint URL. Optional.
+  ///   - scopes: A map of available scopes and their descriptions. REQUIRED.
+  ///
+  /// The authorizationURL should be in the form of a valid URL.
+  ///
+  /// Example:
+  ///   ```dart
+  ///   var implicitFlow = APISecuritySchemeOAuth2Flow.implicit(
+  ///     Uri.parse('https://example.com/oauth/authorize'),
+  ///     Uri.parse('https://example.com/oauth/refresh'),
+  ///     {'read:api': 'Read access to protected resources'},
+  ///   );
+  ///   ```
   APISecuritySchemeOAuth2Flow.implicit(
     this.authorizationURL,
     this.refreshURL,
     this.scopes,
   );
+
+  /// Creates an instance of APISecuritySchemeOAuth2Flow for the Resource Owner Password Credentials flow.
+  ///
+  /// This constructor initializes an OAuth2 flow configuration for the Password grant type.
+  ///
+  /// Parameters:
+  ///   - tokenURL: The token endpoint URL. REQUIRED.
+  ///   - refreshURL: The refresh token endpoint URL. Optional.
+  ///   - scopes: A map of available scopes and their descriptions. REQUIRED.
+  ///
+  /// The tokenURL should be in the form of a valid URL.
+  ///
+  /// Example:
+  ///   ```dart
+  ///   var passwordFlow = APISecuritySchemeOAuth2Flow.password(
+  ///     Uri.parse('https://example.com/oauth/token'),
+  ///     Uri.parse('https://example.com/oauth/refresh'),
+  ///     {'read:api': 'Read access to protected resources'},
+  ///   );
+  ///   ```
   APISecuritySchemeOAuth2Flow.password(
     this.tokenURL,
     this.refreshURL,
     this.scopes,
   );
+
+  /// Creates an instance of APISecuritySchemeOAuth2Flow for the Client Credentials flow.
+  ///
+  /// This constructor initializes an OAuth2 flow configuration for the Client Credentials grant type.
+  ///
+  /// Parameters:
+  ///   - tokenURL: The token endpoint URL. REQUIRED.
+  ///   - refreshURL: The refresh token endpoint URL. Optional.
+  ///   - scopes: A map of available scopes and their descriptions. REQUIRED.
+  ///
+  /// The tokenURL should be in the form of a valid URL.
+  ///
+  /// Example:
+  ///   ```dart
+  ///   var clientFlow = APISecuritySchemeOAuth2Flow.client(
+  ///     Uri.parse('https://example.com/oauth/token'),
+  ///     Uri.parse('https://example.com/oauth/refresh'),
+  ///     {'read:api': 'Read access to protected resources'},
+  ///   );
+  ///   ```
   APISecuritySchemeOAuth2Flow.client(
     this.tokenURL,
     this.refreshURL,
@@ -243,24 +574,102 @@ class APISecuritySchemeOAuth2Flow extends APIObject {
 
   /// The authorization URL to be used for this flow.
   ///
-  /// REQUIRED. This MUST be in the form of a URL.
+  /// This property represents the authorization endpoint URL for OAuth 2.0 flows
+  /// that require user interaction, such as the Authorization Code flow and the
+  /// Implicit flow.
+  ///
+  /// The authorization URL is the endpoint where the resource owner (user) is
+  /// redirected to grant authorization to the client application. It's typically
+  /// used to initiate the OAuth 2.0 authorization process.
+  ///
+  /// This property is REQUIRED for flows that use an authorization endpoint
+  /// (Authorization Code and Implicit flows). It MUST be in the form of a valid URL.
+  ///
+  /// Example:
+  ///   ```dart
+  ///   authorizationURL = Uri.parse('https://example.com/oauth/authorize');
+  ///   ```
+  ///
+  /// Note: This property should not be set for flows that don't use an
+  /// authorization endpoint, such as the Client Credentials flow or the
+  /// Resource Owner Password Credentials flow.
   Uri? authorizationURL;
 
   /// The token URL to be used for this flow.
   ///
-  /// REQUIRED. This MUST be in the form of a URL.
+  /// This property represents the token endpoint URL for OAuth 2.0 flows.
+  /// The token URL is the endpoint where the client application exchanges
+  /// an authorization grant for an access token.
+  ///
+  /// This property is REQUIRED for flows that use a token endpoint
+  /// (Authorization Code, Resource Owner Password Credentials, and Client Credentials flows).
+  /// It MUST be in the form of a valid URL.
+  ///
+  /// Example:
+  ///   ```dart
+  ///   tokenURL = Uri.parse('https://example.com/oauth/token');
+  ///   ```
+  ///
+  /// Note: This property is not used in the Implicit flow, as the access token
+  /// is returned directly from the authorization endpoint in that flow.
   Uri? tokenURL;
 
   /// The URL to be used for obtaining refresh tokens.
   ///
-  /// This MUST be in the form of a URL.
+  /// This property represents the refresh token endpoint URL for OAuth 2.0 flows
+  /// that support token refresh. The refresh URL is used to obtain a new access token
+  /// using a refresh token, without requiring the user to re-authenticate.
+  ///
+  /// This property is OPTIONAL for all OAuth 2.0 flows. If provided, it MUST be in the
+  /// form of a valid URL.
+  ///
+  /// Example:
+  ///   ```dart
+  ///   refreshURL = Uri.parse('https://example.com/oauth/refresh');
+  ///   ```
+  ///
+  /// Note: Not all OAuth 2.0 implementations support refresh tokens. When supported,
+  /// this URL allows clients to refresh their access tokens without user interaction,
+  /// improving the user experience for long-lived applications.
   Uri? refreshURL;
 
   /// The available scopes for the OAuth2 security scheme.
   ///
-  /// REQUIRED. A map between the scope name and a short description for it.
+  /// This property represents a map of OAuth 2.0 scopes available for the security scheme.
+  /// Each key in the map is a scope name, and its corresponding value is a short description of that scope.
+  ///
+  /// Scopes are used to define and limit the level of access granted to a client application.
+  /// They allow for fine-grained control over the permissions given to a client when accessing protected resources.
+  ///
+  /// This property is REQUIRED for all OAuth 2.0 flows defined in the OpenAPI specification.
+  ///
+  /// Example:
+  ///   ```dart
+  ///   scopes = {
+  ///     'read:users': 'Read access to user information',
+  ///     'write:users': 'Write access to user information',
+  ///   };
+  ///   ```
+  ///
+  /// Note: The descriptions should be concise yet informative, helping API consumers
+  /// understand the purpose and implications of each scope.
   Map<String, String>? scopes;
 
+  /// Encodes the OAuth2 flow configuration into a [KeyedArchive] object.
+  ///
+  /// This method is responsible for serializing the properties of the [APISecuritySchemeOAuth2Flow]
+  /// instance into the provided [KeyedArchive] object. It encodes the following properties:
+  ///
+  /// - authorizationURL: The authorization endpoint URL (if applicable)
+  /// - tokenURL: The token endpoint URL (if applicable)
+  /// - refreshURL: The refresh token endpoint URL (if applicable)
+  /// - scopes: A map of available scopes and their descriptions
+  ///
+  /// This method first calls the superclass's encode method to handle any inherited properties,
+  /// then encodes the specific properties of the OAuth2 flow configuration.
+  ///
+  /// Parameters:
+  ///   - object: A [KeyedArchive] to store the encoded OAuth2 flow configuration data.
   @override
   void encode(KeyedArchive object) {
     super.encode(object);
@@ -271,6 +680,21 @@ class APISecuritySchemeOAuth2Flow extends APIObject {
     object.encode("scopes", scopes);
   }
 
+  /// Decodes the OAuth2 flow configuration from a [KeyedArchive] object.
+  ///
+  /// This method is responsible for deserializing the properties of the [APISecuritySchemeOAuth2Flow]
+  /// instance from the provided [KeyedArchive] object. It decodes the following properties:
+  ///
+  /// - authorizationURL: The authorization endpoint URL (if present)
+  /// - tokenURL: The token endpoint URL (if present)
+  /// - refreshURL: The refresh token endpoint URL (if present)
+  /// - scopes: A map of available scopes and their descriptions
+  ///
+  /// This method first calls the superclass's decode method to handle any inherited properties,
+  /// then decodes the specific properties of the OAuth2 flow configuration.
+  ///
+  /// Parameters:
+  ///   - object: A [KeyedArchive] containing the encoded OAuth2 flow configuration data.
   @override
   void decode(KeyedArchive object) {
     super.decode(object);
@@ -283,22 +707,56 @@ class APISecuritySchemeOAuth2Flow extends APIObject {
   }
 }
 
-/// Lists the required security schemes to execute an operation.
+/// Represents a security requirement in the OpenAPI specification.
 ///
 /// The name used for each property MUST correspond to a security scheme declared in [APIComponents.securitySchemes].
-
 /// [APISecurityRequirement] that contain multiple schemes require that all schemes MUST be satisfied for a request to be authorized. This enables support for scenarios where multiple query parameters or HTTP headers are required to convey security information.
-
 /// When a list of [APISecurityRequirement] is defined on the [APIDocument] or [APIOperation], only one of [APISecurityRequirement] in the list needs to be satisfied to authorize the request.
 class APISecurityRequirement extends APIObject {
+  /// Creates an [APISecurityRequirement] instance with the specified security requirements.
+  ///
+  /// The [requirements] parameter is a map where each key corresponds to a security scheme
+  /// declared in [APIComponents.securitySchemes], and the value is a list of scope names
+  /// required for execution (for OAuth2 or OpenID schemes) or an empty list (for other schemes).
+  ///
+  /// Example:
+  ///   ```dart
+  ///   var securityRequirement = APISecurityRequirement({
+  ///     'api_key': [],
+  ///     'oauth2': ['read:api', 'write:api'],
+  ///   });
+  ///   ```
+  ///
+  /// Note: For security schemes other than OAuth2 or OpenID, the list should be empty.
   APISecurityRequirement(this.requirements);
+
+  /// Creates an empty instance of APISecurityRequirement.
+  ///
+  /// This constructor initializes an APISecurityRequirement with no pre-set security requirements.
+  /// It can be used when you need to create a security requirement object that will be
+  /// populated with data later or when you want to manually set the requirements.
   APISecurityRequirement.empty();
 
-  /// Each name MUST correspond to a security scheme which is declared in [APIComponents.securitySchemes].
+  /// A map representing the security requirements for an API operation or the entire API.
   ///
   /// If the security scheme is of type [APISecuritySchemeType.oauth2] or [APISecuritySchemeType.openID], then the value is a list of scope names required for the execution. For other security scheme types, the array MUST be empty.
   Map<String, List<String>>? requirements;
 
+  /// Encodes the security requirements into a [KeyedArchive] object.
+  ///
+  /// This method is responsible for serializing the [requirements] of the [APISecurityRequirement]
+  /// instance into the provided [KeyedArchive] object. It performs the following steps:
+  ///
+  /// 1. Calls the superclass's encode method to handle any inherited properties.
+  /// 2. If [requirements] is not null, it iterates through each key-value pair in the map.
+  /// 3. For each pair, it encodes the key (security scheme name) and its corresponding value
+  ///    (list of scope names or an empty list) into the [KeyedArchive] object.
+  ///
+  /// This encoding process allows the security requirements to be properly serialized
+  /// for use in the OpenAPI specification.
+  ///
+  /// Parameters:
+  ///   - object: A [KeyedArchive] to store the encoded security requirement data.
   @override
   void encode(KeyedArchive object) {
     super.encode(object);
@@ -310,6 +768,25 @@ class APISecurityRequirement extends APIObject {
     }
   }
 
+  /// Decodes the security requirements from a [KeyedArchive] object.
+  ///
+  /// This method is responsible for deserializing the security requirements stored in the
+  /// provided [KeyedArchive] object into the [requirements] property of this [APISecurityRequirement]
+  /// instance. It performs the following steps:
+  ///
+  /// 1. Calls the superclass's decode method to handle any inherited properties.
+  /// 2. Iterates through all keys in the [KeyedArchive] object.
+  /// 3. For each key, it attempts to decode the value as an [Iterable<dynamic>].
+  /// 4. If successful, it converts the decoded value to a [List<String>].
+  /// 5. If [requirements] is null, it initializes it as an empty map.
+  /// 6. Adds the key-value pair to the [requirements] map, where the key is the security
+  ///    scheme name and the value is the list of scope names or an empty list.
+  ///
+  /// This decoding process allows the security requirements to be properly deserialized
+  /// from the OpenAPI specification format.
+  ///
+  /// Parameters:
+  ///   - object: A [KeyedArchive] containing the encoded security requirement data.
   @override
   void decode(KeyedArchive object) {
     super.decode(object);

packages/openapi/lib/src/v3/server.dart

@@ -11,26 +11,96 @@ import 'package:protevus_typeforge/codable.dart';
 import 'package:protevus_openapi/object.dart';
 
 /// An object representing a Server.
+///
+/// This class is used to describe a server in an OpenAPI specification.
+/// It includes information about the server's URL, an optional description,
+/// and any variables that can be used in the URL template.
+///
+/// The [url] property is required and represents the URL to the target host.
+/// It may include server variables in {brackets} for substitution.
+///
+/// The [description] property is optional and can provide additional
+/// information about the server.
+///
+/// The [variables] property is a map of server variables that can be used
+/// for substitution in the URL template.
 class APIServerDescription extends APIObject {
+  /// Creates a new [APIServerDescription] instance.
+  ///
+  /// [url] is a required parameter representing the URL to the target host.
+  /// It may include server variables in {brackets} for substitution.
+  ///
+  /// [description] is an optional parameter that provides additional
+  /// information about the server.
+  ///
+  /// [variables] is an optional parameter representing a map of server
+  /// variables that can be used for substitution in the URL template.
   APIServerDescription(this.url, {this.description, this.variables});
 
+  /// Creates an empty [APIServerDescription] instance.
+  ///
+  /// This constructor initializes an [APIServerDescription] object without setting any of its properties.
+  /// It can be useful when you need to create an instance that will be populated later.
   APIServerDescription.empty();
 
   /// A URL to the target host.
   ///
-  /// REQUIRED. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the OpenAPI document is being served. Variable substitutions will be made when a variable is named in {brackets}.
+  /// This URL is required and represents the location of the target host.
+  /// It supports Server Variables and may be relative, indicating that the host
+  /// location is relative to where the OpenAPI document is being served.
+  ///
+  /// Variable substitutions will be made when a variable is named in {brackets}.
+  /// For example, a URL like "https://{username}.example.com" would allow
+  /// substitution of the {username} part.
+  ///
+  /// This field is crucial for specifying where API requests should be sent.
   Uri? url;
 
   /// An optional string describing the host designated by the URL.
   ///
-  /// CommonMark syntax MAY be used for rich text representation.
+  /// This property provides additional information about the server, which can be useful for API consumers.
+  /// It may include details such as the environment (e.g., production, staging), the purpose of the server,
+  /// or any specific characteristics.
+  ///
+  /// The description can use CommonMark syntax for rich text representation, allowing for formatted text,
+  /// links, and other markup elements.
+  ///
+  /// Example:
+  /// ```
+  /// description: "Production server for the European region"
+  /// ```
+  ///
+  /// This field is optional and can be null if no description is provided.
   String? description;
 
   /// A map between a variable name and its value.
   ///
-  /// The value is used for substitution in the server's URL template.
+  /// This property represents a mapping of server variable names to their corresponding [APIServerVariable] objects.
+  /// These variables can be used for substitution in the server's URL template.
+  ///
+  /// Each key in the map is a string representing the variable name, and the corresponding value
+  /// is an [APIServerVariable] object (or null) that defines the properties of that variable.
+  ///
+  /// For example, if the server URL is "https://{username}.example.com", the variables map might contain
+  /// a key "username" with an [APIServerVariable] value that specifies the default username and possible alternatives.
+  ///
+  /// This field is optional and can be null if no variables are defined for the server.
   Map<String, APIServerVariable?>? variables;
 
+  /// Decodes the [APIServerDescription] object from a [KeyedArchive].
+  ///
+  /// This method is responsible for populating the properties of the [APIServerDescription]
+  /// instance from the provided [KeyedArchive] object. It performs the following steps:
+  ///
+  /// 1. Calls the superclass's decode method to handle any inherited properties.
+  /// 2. Decodes the 'url' field from the archive and assigns it to the [url] property.
+  /// 3. Decodes the 'description' field and assigns it to the [description] property.
+  /// 4. Decodes the 'variables' field as an object map, where each value is an [APIServerVariable].
+  ///    It uses [APIServerVariable.empty()] as a factory function to create new instances.
+  ///
+  /// This method is typically called when deserializing the object from a JSON or similar format.
+  ///
+  /// [object] is the [KeyedArchive] containing the encoded data for this object.
   @override
   void decode(KeyedArchive object) {
     super.decode(object);
@@ -41,6 +111,23 @@ class APIServerDescription extends APIObject {
         object.decodeObjectMap("variables", () => APIServerVariable.empty());
   }
 
+  /// Encodes the [APIServerDescription] object into a [KeyedArchive].
+  ///
+  /// This method is responsible for serializing the properties of the [APIServerDescription]
+  /// instance into the provided [KeyedArchive] object. It performs the following steps:
+  ///
+  /// 1. Calls the superclass's encode method to handle any inherited properties.
+  /// 2. Checks if the [url] property is null. If it is, an [ArgumentError] is thrown
+  ///    because the 'url' field is required for a valid [APIServerDescription].
+  /// 3. Encodes the [url] property into the archive with the key "url".
+  /// 4. Encodes the [description] property into the archive with the key "description".
+  /// 5. Encodes the [variables] property as an object map into the archive with the key "variables".
+  ///
+  /// This method is typically called when serializing the object to JSON or a similar format.
+  ///
+  /// [object] is the [KeyedArchive] where the encoded data for this object will be stored.
+  ///
+  /// Throws an [ArgumentError] if the [url] property is null.
   @override
   void encode(KeyedArchive object) {
     super.encode(object);
@@ -58,28 +145,92 @@ class APIServerDescription extends APIObject {
 }
 
 /// An object representing a Server Variable for server URL template substitution.
+///
+/// This class extends [APIObject] and represents a variable that can be used
+/// in a server URL template. It includes properties for the default value,
+/// available values (enum), and an optional description.
+///
+/// The [defaultValue] is required and represents the value to be used if no
+/// other value is provided.
+///
+/// [availableValues] is an optional list of allowed values for the variable.
+///
+/// [description] is an optional field providing additional information about
+/// the variable.
 class APIServerVariable extends APIObject {
+  /// Creates a new [APIServerVariable] instance.
+  ///
+  /// [defaultValue] is a required parameter representing the default value to use for substitution.
+  /// This value MUST be provided by the consumer.
+  ///
+  /// [availableValues] is an optional parameter that provides a list of allowed values for the variable.
+  /// If provided, it represents an enumeration of string values to be used if the substitution options
+  /// are from a limited set.
+  ///
+  /// [description] is an optional parameter that provides additional information about the server variable.
+  /// CommonMark syntax MAY be used for rich text representation.
   APIServerVariable(
     this.defaultValue, {
     this.availableValues,
     this.description,
   });
 
+  /// Creates an empty [APIServerVariable] instance.
+  ///
+  /// This constructor initializes an [APIServerVariable] object without setting any of its properties.
+  /// It can be useful when you need to create an instance that will be populated later.
   APIServerVariable.empty();
 
   /// An enumeration of string values to be used if the substitution options are from a limited set.
+  ///
+  /// This property represents an optional list of allowed values for the server variable.
+  /// If provided, it restricts the possible values that can be used for substitution
+  /// in the server URL template to this specific set of strings.
+  ///
+  /// When defined, the variable value used for URL substitution must be one of the values
+  /// listed in this array. This allows for validation and helps ensure that only
+  /// pre-defined, valid values are used in the server URL.
+  ///
+  /// The list can be null if there are no restrictions on the possible values for the variable.
   List<String>? availableValues;
 
-  /// The default value to use for substitution, and to send, if an alternate value is not supplied.
+  /// The default value to use for substitution in the server URL template.
   ///
   /// REQUIRED. Unlike the Schema Object's default, this value MUST be provided by the consumer.
   String? defaultValue;
 
   /// An optional description for the server variable.
   ///
-  /// CommonMark syntax MAY be used for rich text representation.
+  /// This property provides additional information about the server variable,
+  /// which can be helpful for API consumers to understand its purpose or usage.
+  /// The description can include details such as the expected format of the value,
+  /// any constraints, or examples of valid inputs.
+  ///
+  /// CommonMark syntax MAY be used for rich text representation, allowing for
+  /// formatted text, links, and other markup elements to enhance readability
+  /// and provide more detailed explanations.
+  ///
+  /// This field is optional and can be null if no description is provided.
+  ///
+  /// Example:
+  /// ```
+  /// description: "The username for authentication. Use 'demo' for testing."
+  /// ```
   String? description;
 
+  /// Decodes the [APIServerVariable] object from a [KeyedArchive].
+  ///
+  /// This method is responsible for populating the properties of the [APIServerVariable]
+  /// instance from the provided [KeyedArchive] object. It performs the following steps:
+  ///
+  /// 1. Calls the superclass's decode method to handle any inherited properties.
+  /// 2. Decodes the 'enum' field from the archive, casts it to a List<String>, and assigns it to [availableValues].
+  /// 3. Decodes the 'default' field and assigns it to the [defaultValue] property.
+  /// 4. Decodes the 'description' field and assigns it to the [description] property.
+  ///
+  /// This method is typically called when deserializing the object from a JSON or similar format.
+  ///
+  /// [object] is the [KeyedArchive] containing the encoded data for this object.
   @override
   void decode(KeyedArchive object) {
     super.decode(object);
@@ -90,6 +241,23 @@ class APIServerVariable extends APIObject {
     description = object.decode("description");
   }
 
+  /// Encodes the [APIServerVariable] object into a [KeyedArchive].
+  ///
+  /// This method is responsible for serializing the properties of the [APIServerVariable]
+  /// instance into the provided [KeyedArchive] object. It performs the following steps:
+  ///
+  /// 1. Calls the superclass's encode method to handle any inherited properties.
+  /// 2. Checks if the [defaultValue] property is null. If it is, an [ArgumentError] is thrown
+  ///    because the 'defaultValue' field is required for a valid [APIServerVariable].
+  /// 3. Encodes the [availableValues] property into the archive with the key "enum".
+  /// 4. Encodes the [defaultValue] property into the archive with the key "default".
+  /// 5. Encodes the [description] property into the archive with the key "description".
+  ///
+  /// This method is typically called when serializing the object to JSON or a similar format.
+  ///
+  /// [object] is the [KeyedArchive] where the encoded data for this object will be stored.
+  ///
+  /// Throws an [ArgumentError] if the [defaultValue] property is null.
   @override
   void encode(KeyedArchive object) {
     super.encode(object);

packages/openapi/lib/src/v3/types.dart

@@ -7,9 +7,33 @@
  * file that was distributed with this source code.
  */
 
+/// Represents the different data types that can be used in an API.
+///
+/// This enumeration defines the following types:
+/// - [string]: Represents a sequence of characters.
+/// - [number]: Represents a numeric value, which can include decimals.
+/// - [integer]: Represents a whole number without decimals.
+/// - [boolean]: Represents a true or false value.
+/// - [array]: Represents a collection of values.
+/// - [object]: Represents a complex data structure with key-value pairs.
 enum APIType { string, number, integer, boolean, array, object }
 
+/// A utility class for encoding and decoding [APIType] values.
+///
+/// This class provides static methods to convert between [APIType] enum values
+/// and their corresponding string representations.
 class APITypeCodec {
+  /// Decodes a string representation of an [APIType] to its corresponding enum value.
+  ///
+  /// This method takes a [String] parameter [type] and returns the corresponding
+  /// [APIType] enum value. If the input string doesn't match any known type,
+  /// the method returns null.
+  ///
+  /// Parameters:
+  ///   - type: A [String] representing the API type to be decoded.
+  ///
+  /// Returns:
+  ///   The corresponding [APIType] enum value, or null if no match is found.
   static APIType? decode(String? type) {
     switch (type) {
       case "string":
@@ -29,6 +53,17 @@ class APITypeCodec {
     }
   }
 
+  /// Encodes an [APIType] enum value to its corresponding string representation.
+  ///
+  /// This method takes an [APIType] parameter [type] and returns the corresponding
+  /// string representation. If the input type is null or doesn't match any known type,
+  /// the method returns null.
+  ///
+  /// Parameters:
+  ///   - type: An [APIType] enum value to be encoded.
+  ///
+  /// Returns:
+  ///   The corresponding [String] representation of the [APIType], or null if the input is null or no match is found.
   static String? encode(APIType? type) {
     switch (type) {
       case APIType.string: