koi_swagger_parser/doc/DIAGNOSTICS.md

Diagnostics

English | Chinese (Simplified)

Configuration, loading, parsing, rendering, and lifecycle issues are reported as KoiDiagnostic values:

class KoiDiagnostic {
  final String code;
  final DiagnosticSeverity severity; // info | warning | error
  final String message;
  final String? source;
  final String? location;
}

code is the stable machine-readable identifier. Message wording may improve between releases. source identifies a configuration path, document URL/file, or generated file. location usually contains a JSONPath, JSON Pointer, or other logical location inside the source.

Severity behavior

• info: a normal decision, such as skipping an unchanged generation.
• warning: output remains reliable, but a rename, safe degradation, or explicitly omitted non-blocking capability requires attention.
• error: continuing could produce an invalid client; generation throws KoiDiagnosticException.

The CLI prints warnings and errors by default. --verbose also prints informational diagnostics and failure stack traces.

Library callers can inspect diagnostics:

try {
  final result = await const KoiSwaggerParser().generate();
  for (final item in result.diagnostics) {
    print(item.format());
  }
} on KoiDiagnosticException catch (error) {
  for (final item in error.diagnostics) {
    print(item.format());
  }
}

Automation should match code, not message text. Assert source or location as well when the distinction matters.

Common codes

Configuration

Code	Meaning and remediation
config.missing_sources	Add at least one enabled input.swagger_urls entry.
config.unknown_key	Correct the spelling or remove a field not recognized by this version; warning.
config.invalid_section	Replace a scalar/list with the expected YAML map.
config.invalid_string / config.invalid_boolean	Correct the YAML scalar type.
config.invalid_string_list	Use a list of strings for include/exclude filters.
config.invalid_filter_regex	Correct the Dart expression after regex:.
config.no_outputs_enabled	API and model generation cannot both be disabled.
config.api_requires_models	The current API renderer requires generated models.
config.unsupported_api_renderer	Keep use_retrofit: true; no other API renderer is public yet.
config.external_wrapper_import_required	Add external_generic.import.
config.mapping_target_collision	Give mapping sources distinct target Dart names.
config.import_mapping_conflict	Use one import for a mapped Dart type.
config.conflicting_schema_mapping	Do not both rename and externally replace the same schema.
config.ambiguous_enum_mapping	Use unambiguous typed enum wire values.

Documents and references

Code	Meaning and remediation
openapi.missing_version / openapi.unsupported_version	Supply an OpenAPI 3.0.x or 3.1.x document.
openapi.invalid_info / openapi.invalid_paths	Correct the corresponding core document structure.
openapi.source_load_failed / openapi.source_http_error	Check the file path, URL, access, and response status.
openapi.unresolved_ref	The local JSON Pointer does not exist.
openapi.unresolved_external_ref	The external resource or fragment does not exist or cannot be loaded.
openapi.external_ref_not_bundled	Reference normalization failed; inspect preceding source/resolver diagnostics.
openapi.external_component_renamed	An external component conflict was renamed deterministically; warning.
openapi.multisource_component_renamed	A component conflict across roots was renamed deterministically; warning.
openapi.multisource_operation_conflict	Two roots define the same method/path; remove or separate one definition.
openapi.callbacks_not_supported / openapi.webhooks_not_supported	Reverse-call clients are not generated; warning.
openapi.links_not_supported	Link Object call relationships are not generated; warning.

Parameters, requests, and responses

Code	Meaning and remediation
openapi.invalid_parameter_style	Use a style valid for the parameter location.
openapi.deep_object_requires_object	A deepObject parameter needs an object schema.
openapi.delimited_parameter_requires_array	A space/pipe-delimited parameter needs an array schema.
openapi.parameter_content_count	Parameter Object content must contain exactly one media type.
openapi.request_body_schema_missing	Add a schema to the selected request media type.
openapi.unsupported_request_content_type	Use a supported request codec or map the endpoint manually.
openapi.unsupported_response_content_type	Use a supported response codec or map the endpoint manually.
openapi.success_response_missing	Add an explicit 2xx response; default is not success.
openapi.multiple_success_response_types	Multiple successful JSON body types converge on Object?; warning.
openapi.mixed_success_media_types	Binary/stream and JSON successes cannot be decoded safely by one generated method.
openapi.path_parameter_forced_required	A path parameter declared optional is forced to required; warning.

Schemas and names

Code	Meaning and remediation
openapi.property_read_write_only	A property cannot be both read-only and write-only.
openapi.invalid_additional_properties	Use a boolean or Schema Object.
openapi.property_name_collision	An automatic suffix prevented a Dart field collision; warning.
openapi.operation_name_collision	An automatic suffix prevented a method collision; warning.
openapi.operation_argument_name_collision	A parameter conflicts with a body, cancel token, or another argument.
openapi.duplicate_enum_member_name	Multiple wire values map to one name; a suffix was added.
openapi.enum_member_name_sanitized	An enum member name was changed into a valid Dart identifier.
filter.required_model_excluded	A selected API needs an excluded model; include it or exclude its consumers.
filter.model_pattern_unmatched	An included_models pattern matched no schema.

Servers and security

Code	Meaning and remediation
openapi.server_url_missing	Add a non-empty server URL.
openapi.server_variable_default_missing	Give every server variable a default value.
openapi.server_variable_default_invalid	Make the default one of the declared enum values.
openapi.server_variable_unresolved	Define every variable used by the server URL.
openapi.unknown_security_scheme	Define the referenced scheme in components.
openapi.unsupported_security_scheme	The scheme is retained only where documented or rejected.
openapi.http_auth_requires_custom_interceptor	Implement credential injection in the host Dio layer; warning.

Generation lifecycle

Code	Meaning and remediation
lifecycle.unchanged_skipped	Hashes and files match; generation was safely skipped.
lifecycle.manifest_invalid	The old manifest is corrupt; output is rebuilt without trusting its deletion list.
lifecycle.manifest_version_ignored	The manifest schema is incompatible; its deletion list is ignored.
lifecycle.output_outside_managed_roots	Renderer output escaped the API/model roots and was rejected.
lifecycle.duplicate_output_path	Two rendered files target the same path with different content.
lifecycle.stale_path_outside_roots	A former path is outside current roots and is preserved.
lifecycle.stale_file_modified	A stale generated file was edited and is preserved for manual review.
lifecycle.generated_file_missing	A primary generated file disappeared during fix/format/build processing.
lifecycle.control_file_not_stale	A lifecycle control file is never treated as stale output.

Design principles

1. Unresolved references, invalid wire styles, and unsupported codecs do not silently become dynamic.
2. Safe, compilable automatic renaming can continue with a warning.
3. Unsupported constructs that do not invalidate other output are explicitly omitted with a warning.
4. Stale cleanup preserves files whenever containment or hash ownership is uncertain.
5. Diagnostics include component, operation, parameter, or file context when available.

New codes can be added in minor releases. Existing automation should treat unknown warning codes as reviewable and unknown error codes as blocking.