AgentSkillsCN

swagger

为affolterNET.Web.Bff配置Swagger/OpenAPI文档。在设置API文档或自定义Swagger UI时使用此方法。

SKILL.md
--- frontmatter
name: swagger
description: Configure Swagger/OpenAPI documentation for affolterNET.Web.Bff. Use when setting up API documentation or customizing Swagger UI.

Swagger/OpenAPI Configuration

Configure Swagger/OpenAPI documentation for your BFF.

For complete reference, see Library Guide.

Quick Start

appsettings.json

json
{
  "affolterNET": {
    "Web": {
      "Swagger": {
        "Enabled": true,
        "Title": "My BFF API",
        "Version": "v1",
        "Description": "Backend-for-Frontend API documentation"
      }
    }
  }
}

Configuration Options

PropertyTypeDefaultDescription
Enabledbooltrue (dev)Enable Swagger UI
Titlestring"API"API title
Versionstring"v1"API version
DescriptionstringnullAPI description
RoutePrefixstring"swagger"URL prefix

BFF-Specific Endpoints

The BFF exposes these endpoints in Swagger:

EndpointDescription
/bff/account/loginInitiates login
/bff/account/logoutLogs out user
/bff/account/userCurrent user info
/api/*Proxied API routes

Controller Documentation

csharp
/// <summary>
/// User profile operations
/// </summary>
[ApiController]
[Route("api/[controller]")]
public class ProfileController : ControllerBase
{
    /// <summary>
    /// Gets the current user's profile
    /// </summary>
    /// <returns>User profile data</returns>
    /// <response code="200">Profile retrieved</response>
    /// <response code="401">Not authenticated</response>
    [HttpGet]
    [Authorize]
    [ProducesResponseType(typeof(UserProfile), 200)]
    [ProducesResponseType(401)]
    public IActionResult GetProfile() { ... }
}

Development vs Production

json
{
  "affolterNET": {
    "Web": {
      "Swagger": {
        "Enabled": true  // Set false in production
      }
    }
  }
}

Or use environment-specific configuration:

json
// appsettings.Development.json
{
  "affolterNET": {
    "Web": {
      "Swagger": {
        "Enabled": true
      }
    }
  }
}

// appsettings.Production.json
{
  "affolterNET": {
    "Web": {
      "Swagger": {
        "Enabled": false
      }
    }
  }
}

Troubleshooting

Swagger UI shows 401

  • Swagger is served before authentication
  • Check if path is correctly excluded from auth

YARP routes not visible

  • YARP routes are not documented in Swagger
  • Document backend API separately