Add operation and schema transform examples

Add examples for DI-activated operation and schema transformers.

Author: martincostello

src/OpenApi/sample/Program.cs

@@ -21,6 +21,8 @@
     options.AddDocumentTransformer<BearerSecuritySchemeTransformer>();
 });
 builder.Services.AddOpenApi("v2", options => {
+    options.AddSchemaTransformer<AddExternalDocsTransformer>();
+    options.AddOperationTransformer<AddExternalDocsTransformer>();
     options.AddDocumentTransformer(new AddContactTransformer());
     options.AddDocumentTransformer((document, context, token) => {
         document.Info.License = new OpenApiLicense { Name = "MIT" };
@@ -81,7 +83,8 @@
 v2.MapGet("/users", () => new [] { "alice", "bob" })
     .WithTags("users");
 
-v2.MapPost("/users", () => Results.Created("/users/1", new { Id = 1, Name = "Test user" }));
+v2.MapPost("/users", () => Results.Created("/users/1", new { Id = 1, Name = "Test user" }))
+  .WithName("CreateUser");
 
 responses.MapGet("/200-add-xml", () => new TodoWithDueDate(1, "Test todo", false, DateTime.Now.AddDays(1), DateTime.Now))
     .Produces<Todo>(additionalContentTypes: "text/xml");

src/OpenApi/sample/Transformers/AddExternalDocsTransformer.cs

@@ -0,0 +1,42 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using Microsoft.AspNetCore.OpenApi;
+using Microsoft.OpenApi.Models;
+
+namespace Sample.Transformers;
+
+public sealed class AddExternalDocsTransformer(IConfiguration configuration) : IOpenApiOperationTransformer, IOpenApiSchemaTransformer
+{
+    public Task TransformAsync(OpenApiOperation operation, OpenApiOperationTransformerContext context, CancellationToken cancellationToken)
+    {
+        if (operation.OperationId is { Length: > 0 } id &&
+            Uri.TryCreate(configuration["DocumentationBaseUrl"], UriKind.Absolute, out var baseUri))
+        {
+            var url = new Uri(baseUri, $"/api/docs/operations/{Uri.EscapeDataString(id)}");
+
+            operation.ExternalDocs = new OpenApiExternalDocs
+            {
+                Description = "Documentation for this OpenAPI endpoint",
+                Url = url
+            };
+        }
+
+        return Task.CompletedTask;
+    }
+
+    public Task TransformAsync(OpenApiSchema schema, OpenApiSchemaTransformerContext context, CancellationToken cancellationToken)
+    {
+        if (Uri.TryCreate(configuration["DocumentationBaseUrl"], UriKind.Absolute, out var baseUri))
+        {
+            var url = new Uri(baseUri, $"/api/docs/schemas/{Uri.EscapeDataString(schema.Type)}");
+
+            schema.ExternalDocs = new OpenApiExternalDocs
+            {
+                Description = "Documentation for this OpenAPI schema",
+                Url = url
+            };
+        }
+        return Task.CompletedTask;
+    }
+}

src/OpenApi/sample/appsettings.json

@@ -1,4 +1,5 @@
 {
+  "DocumentationBaseUrl": "https://example.com",
   "Logging": {
     "LogLevel": {
       "Default": "Information",

src/OpenApi/test/Integration/snapshots/OpenApiDocumentIntegrationTests.VerifyOpenApiDocument_documentName=v2.verified.txt

@@ -34,6 +34,11 @@
         "tags": [
           "Sample"
         ],
+        "externalDocs": {
+          "description": "Documentation for this OpenAPI endpoint",
+          "url": "https://example.com/api/docs/operations/CreateUser"
+        },
+        "operationId": "CreateUser",
         "responses": {
           "200": {
             "description": "OK"
@@ -48,6 +53,10 @@
         "type": "array",
         "items": {
           "type": "string"
+        },
+        "externalDocs": {
+          "description": "Documentation for this OpenAPI schema",
+          "url": "https://example.com/api/docs/schemas/array"
         }
       }
     }