Skip to content

feat: OpenAPI metadata extension methods for MapCommand, MapQuery, MapStreamQuery (opt-in and global) #288

@samtrion

Description

@samtrion

User Story

As a developer exposing Pulse endpoints via Minimal API, I want OpenAPI metadata (summaries, response types, tags) applied automatically or opt-in to MapCommand, MapQuery, and MapStreamQuery endpoints, so that my Swagger/OpenAPI documentation is accurate without manual configuration per endpoint.


Requirements

  • Create src/NetEvolve.Pulse.AspNetCore/RouteHandlerBuilderExtensions.cs with opt-in extension methods:
    • WithPulseSummary(): reads from XML doc file via XmlDocumentationReader; falls back to type name.
    • WithPulseDescription(string description).
    • WithPulseTag(string tag).
    • WithPulseProduces(): ProducesResponseType(200).
    • WithPulseStreamProduces(): ext/event-stream and �pplication/x-ndjson content types.
  • Create src/NetEvolve.Pulse.AspNetCore/Internals/XmlDocumentationReader.cs:
    • Parses *.xml files from assembly output directory.
    • TryGetSummary(Type type, out string? summary) with ConcurrentDictionary cache.
    • No-op (returns
      ull) when XML documentation file absent.
  • Create src/NetEvolve.Pulse.AspNetCore/OpenApiMediatorBuilderExtensions.cs:
    csharp public static IMediatorBuilder EnableOpenApiMetadata(this IMediatorBuilder builder)
    Sets OpenApiMetadataEnabled = true via IOptions.
  • Update MapCommand, MapQuery, MapStreamQuery in EndpointRouteBuilderExtensions.cs: auto-apply WithPulseSummary() and WithPulseProduces() when OpenApiMetadataEnabled = true.

Acceptance Criteria

  • WithPulseSummary() returns XML text when present; type name as fallback.
  • WithPulseProduces() sets correct status code and type.
  • EnableOpenApiMetadata() causes auto-application in all three Map* methods.
  • XmlDocumentationReader caches results; missing XML file does not throw.
  • Unit tests cover all extension methods and XmlDocumentationReader.

Metadata

Metadata

Assignees

No one assigned

    Labels

    type:featureIndicates a new feature or enhancement to be added.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions