Overview

Silky generates Swagger (OpenAPI) documentation automatically from service entry definitions. The gateway aggregates documentation from all services and exposes a unified Swagger UI.

Installation

Service Side

<PackageReference Include="Silky.Swagger.Gen" Version="3.9.2" />

Gateway Side

<PackageReference Include="Silky.Http.Swagger" Version="3.9.2" />

Basic Configuration

Startup.cs (Gateway)

public void ConfigureServices(IServiceCollection services)
{
    services.AddSilkyHttpCore()
            .AddSwaggerDocuments();
}

public void Configure(IApplicationBuilder app)
{
    app.UseSwagger();
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "My Application V1");
        c.RoutePrefix = string.Empty;   // Serve Swagger UI at root
    });

    app.UseSilkyRpcProxy();
}

appsettings.json

{
  "swagger": {
    "enabled": true,
    "title": "My Silky Application",
    "version": "v1",
    "description": "Silky-powered microservice API",
    "contact": {
      "name": "Dev Team",
      "email": "dev@example.com",
      "url": "https://example.com"
    },
    "license": {
      "name": "MIT",
      "url": "https://opensource.org/licenses/MIT"
    }
  }
}

Service Entry Annotations

Use standard XML doc comments and attributes to enrich the generated Swagger:

[ServiceRoute]
public interface IOrderAppService
{
    /// <summary>
    /// Get an order by ID
    /// </summary>
    /// <param name="id">Order ID</param>
    /// <returns>Order details</returns>
    [HttpGet("{id}")]
    Task<OrderOutput> GetAsync(long id);

    /// <summary>
    /// Create a new order
    /// </summary>
    [HttpPost]
    [SwaggerOperation(Summary = "Create Order", Tags = new[] { "Orders" })]
    Task<CreateOrderOutput> CreateOrderAsync(CreateOrderInput input);
}

Authorization in Swagger UI

Enable Bearer token input in Swagger UI for testing protected endpoints:

services.AddSwaggerGen(c =>
{
    c.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
    {
        Type = SecuritySchemeType.Http,
        Scheme = "bearer",
        BearerFormat = "JWT",
        Description = "Enter your JWT token"
    });
    c.AddSecurityRequirement(new OpenApiSecurityRequirement
    {
        {
            new OpenApiSecurityScheme
            {
                Reference = new OpenApiReference
                {
                    Type = ReferenceType.SecurityScheme,
                    Id = "Bearer"
                }
            },
            Array.Empty<string>()
        }
    });
});

Multiple API Groups

Separate services into API groups by specifying the group name on the module or route:

{
  "swagger": {
    "groups": [
      { "name": "order", "title": "Order API", "version": "v1" },
      { "name": "account", "title": "Account API", "version": "v1" }
    ]
  }
}

Accessing the Swagger UI

EnvironmentURL
Gatewayhttp://gateway-host/swagger
WebHost (with Swagger enabled)http://service-host:5000/swagger