Ability to provide additional documentation for operations endpoint

[bjornharrtell]

When enabling/implementing operations as described in https://www.jsonapi.net/usage/writing/bulk-batch-operations.html i.e with a OperationsController class, the generated openapi documentation provides some general information. As far as I've been able to figure out it's not possible to customize / add to the generated documentation.

Rationale is that there can be some system / data model specific rules that apply that is important for a third party to know.

[bkoelman]

Well, you can always register your own implementation of Swashbuckle's IOperationFilter, similar to

JsonApiDotNetCore/src/JsonApiDotNetCore.OpenApi.Swashbuckle/SwaggerComponents/DocumentationOpenApiOperationFilter.cs

Line 604 in b7a7307

private static void ApplyPostOperations(OpenApiOperation operation)

.

I'd like to explore if we can push some of that logic into the API Explorer metadata instead of post-processing, but never got around to that yet.

What specifically are you looking to accomplish?

[bjornharrtell]

In this case I would like to add some free form text as SetOperationSummary with some references to other documentation perhaps. It seems overkill to replicate a full implementation of IOperationFilter for that but I suppose it should work.

[bkoelman]

I meant to add your own filter in addition to the existing one, where you'd overwrite or augment the summary node. There's no need to replace the existing filter. Adding filters is pretty common with Swashbuckle. IOperationFilter is their extensibility point, not ours. In OpenAPI, an endpoint is called an operation, not to be confused with JSON:API operations.

This way, if we refactor the current filter or remove it entirely later, you're not affected.

[bkoelman]

Here's an example: #1910. It allows for a very flexible composition of documentation fragments, based on the specifics of your codebase.

[bjornharrtell]

@bkoelman I understand now and it works well for my use case. The issue was indeed that I was confused and thought IOperationFilter was an JADNC extension. Thank you for the the demo which made it very clear.