|
1 | 1 | ### Endpoint-specific OpenAPI operation transformers |
2 | 2 |
|
3 | | -OpenAPI [operation transformers](<xref:fundamentals/openapi/customize-openapi#use-operation-transformers>) can now be registered directly on individual endpoints using the `AddOpenApiOperationTransformer` extension method. This allows customization of OpenAPI metadata to be colocated with the endpoint definition, rather than requiring global configuration with path-based conditional logic. |
| 3 | +Endpoint-specific operation transformers enable fine-grained customization of OpenAPI documentation for individual route endpoints. This feature allows developers to tailor Swagger/OpenAPI metadata and descriptions on a per-action or per-route basis, enhancing extensibility for advanced API scenarios. |
4 | 4 |
|
5 | | -Prior to this feature, modifying OpenAPI data for specific endpoints required registering a global operation transformer and implementing conditional logic to target specific endpoints. For example: |
6 | | - |
7 | | -```csharp |
8 | | -builder.Services.AddOpenApi(options => |
9 | | -{ |
10 | | - options.AddOperationTransformer((operation, context, ct) => |
11 | | - { |
12 | | - if (context.Description.RelativePath == "deprecated-endpoint") |
13 | | - { |
14 | | - operation.Deprecated = true; |
15 | | - } |
16 | | - |
17 | | - return Task.CompletedTask; |
18 | | - }); |
19 | | -}); |
20 | | -``` |
21 | | - |
22 | | -With the new `AddOpenApiOperationTransformer` API, the same customization can be applied directly to the endpoint, with access to the full operation context as well: |
23 | | - |
24 | | -```csharp |
25 | | -app.MapGet("/deprecated-endpoint", () => "This endpoint is old and should not be used anymore") |
26 | | -.AddOpenApiOperationTransformer((operation, context, cancellationToken) => |
27 | | -{ |
28 | | - operation.Deprecated = true; |
29 | | - |
30 | | - return Task.CompletedTask; |
31 | | -}); |
32 | | -``` |
33 | | - |
34 | | -This approach improves code readability and maintainability by keeping endpoint-specific customizations close to the endpoint definitions. The `AddOpenApiOperationTransformer` method provides access to the full <xref:Microsoft.AspNetCore.OpenApi.OpenApiOperationTransformerContext>, enabling comprehensive customization of the OpenAPI operation, including: |
35 | | - |
36 | | -* Setting operation properties like `Deprecated`, `Summary`, or `Description` |
37 | | -* Customizing response descriptions |
38 | | -* Adding or modifying security requirements |
39 | | -* Modifying parameters or request bodies |
| 5 | +For implementation details and code samples, see <xref:fundamentals/openapi/customize-openapi#use-operation-transformers>. |
0 commit comments