Skip to main content

Attribute Reference

This guide provides comprehensive documentation for all attributes available in LambdaOpenAPI. Use these attributes to customize the generated OpenAPI specification for your AWS Lambda functions.

Table of Contents​

Assembly-Level Attributes​

Method-Level Attributes​

Property/Parameter Attributes​

OpenApiInfoAttribute​

Specifies global OpenAPI document information at the assembly level. Use this attribute to set the API title, version, description, and other metadata that appears in the generated OpenAPI specification's info section.

Target: Assembly

Constructor Parameters​

ParameterTypeRequiredDefaultDescription
titlestringYes—The title of the API
versionstringNo"1.0.0"The version of the API

Properties​

PropertyTypeDescription
TitlestringGets the title of the API
VersionstringGets the version of the API
DescriptionstringGets or sets a description of the API
TermsOfServicestringGets or sets the URL to the Terms of Service
ContactNamestringGets or sets the contact name
ContactEmailstringGets or sets the contact email
ContactUrlstringGets or sets the contact URL
LicenseNamestringGets or sets the license name
LicenseUrlstringGets or sets the license URL

When to Use​

Use this attribute at the assembly level to configure the OpenAPI document's info section. This is typically placed in AssemblyInfo.cs or at the top of any .cs file in your project. Without this attribute, the API title defaults to "API Documentation" and version to "1.0.0".

Examples​

Basic usage:

[assembly: OpenApiInfo("My API", "1.0.0")]

With description:

[assembly: OpenApiInfo("Products API", "2.0.0", 
    Description = "API for managing products in the catalog")]

Full metadata:

[assembly: OpenApiInfo("E-Commerce API", "1.0.0",
    Description = "Complete e-commerce API for managing products, orders, and customers",
    TermsOfService = "https://example.com/terms",
    ContactName = "API Support",
    ContactEmail = "api-support@example.com",
    ContactUrl = "https://example.com/support",
    LicenseName = "MIT",
    LicenseUrl = "https://opensource.org/licenses/MIT")]

OpenApiSecuritySchemeAttribute​

Defines a security scheme for the OpenAPI specification. Apply this attribute at the assembly level to define security schemes that can be referenced by endpoints.

Target: Assembly

Allow Multiple: Yes

Constructor Parameters​

ParameterTypeRequiredDescription
schemeIdstringYesThe unique identifier for this security scheme

Properties​

PropertyTypeDefaultDescription
TypeOpenApiSecuritySchemeTypeApiKeyThe type of security scheme (ApiKey, Http, OAuth2, OpenIdConnect)
ApiKeyNamestringnullThe name of the API key (for ApiKey type)
ApiKeyLocationApiKeyLocationHeaderThe location of the API key (Header, Query, Cookie)
AuthorizationUrlstringnullThe authorization URL (for OAuth2 type)
TokenUrlstringnullThe token URL (for OAuth2 type)
ScopesstringnullAvailable scopes in format "scope1:Description 1,scope2:Description 2"
HttpSchemestringnullThe HTTP authentication scheme name (for Http type, e.g., "bearer", "basic")
BearerFormatstringnullThe bearer format hint (for Http type with bearer scheme, e.g., "JWT")
OpenIdConnectUrlstringnullThe OpenID Connect URL (for OpenIdConnect type)
DescriptionstringnullA description of the security scheme

When to Use​

Use this attribute to define security schemes for your API. Security schemes are only added to the OpenAPI specification when this attribute is present.

Examples​

API Key Authentication:

[assembly: OpenApiSecurityScheme("apiKey",
    Type = OpenApiSecuritySchemeType.ApiKey,
    ApiKeyName = "x-api-key",
    ApiKeyLocation = ApiKeyLocation.Header,
    Description = "API key authentication via header")]

OAuth2 with Authorization Code Flow:

[assembly: OpenApiSecurityScheme("oauth2",
    Type = OpenApiSecuritySchemeType.OAuth2,
    AuthorizationUrl = "https://auth.example.com/authorize",
    TokenUrl = "https://auth.example.com/token",
    Scopes = "read:Read access,write:Write access",
    Description = "OAuth 2.0 authentication")]

Bearer Token (JWT):

[assembly: OpenApiSecurityScheme("bearerAuth",
    Type = OpenApiSecuritySchemeType.Http,
    HttpScheme = "bearer",
    BearerFormat = "JWT",
    Description = "JWT Bearer token authentication")]

Multiple Security Schemes:

[assembly: OpenApiSecurityScheme("apiKey",
    Type = OpenApiSecuritySchemeType.ApiKey,
    ApiKeyName = "x-api-key",
    ApiKeyLocation = ApiKeyLocation.Header)]

[assembly: OpenApiSecurityScheme("oauth2",
    Type = OpenApiSecuritySchemeType.OAuth2,
    AuthorizationUrl = "https://auth.example.com/authorize",
    TokenUrl = "https://auth.example.com/token",
    Scopes = "read:Read access,write:Write access")]

OpenApiServerAttribute​

Specifies server URLs for the OpenAPI specification. Apply this attribute at the assembly level to define the base URLs where the API is hosted.

Target: Assembly

Allow Multiple: Yes

Constructor Parameters​

ParameterTypeRequiredDescription
urlstringYesThe URL of the server

Properties​

PropertyTypeDefaultDescription
Urlstring—Gets the URL of the server
DescriptionstringnullGets or sets a description of the server

When to Use​

Use this attribute to define the server URLs where your API is hosted. This is useful for:

  • Documenting production, staging, and development environments
  • Providing base URLs for API consumers
  • Supporting multiple deployment environments in a single specification

When no [OpenApiServer] attributes are present, the servers section is omitted from the specification entirely.

Examples​

Single server:

[assembly: OpenApiServer("https://api.example.com/v1", Description = "Production server")]

Multiple environments:

[assembly: OpenApiServer("https://api.example.com/v1", Description = "Production server")]
[assembly: OpenApiServer("https://staging-api.example.com/v1", Description = "Staging server")]
[assembly: OpenApiServer("https://localhost:5000", Description = "Local development")]

OpenApiTagDefinitionAttribute​

Defines a tag with metadata for the OpenAPI specification. Tags defined at the assembly level appear in the specification's tags array with descriptions and optional external documentation links.

Target: Assembly

Allow Multiple: Yes

Constructor Parameters​

ParameterTypeRequiredDescription
namestringYesThe name of the tag

Properties​

PropertyTypeDefaultDescription
Namestring—Gets the name of the tag
DescriptionstringnullGets or sets a description of the tag
ExternalDocsUrlstringnullGets or sets the URL for external documentation about this tag
ExternalDocsDescriptionstringnullGets or sets a description for the external documentation

When to Use​

Use this attribute to provide rich metadata for tags used in your API. While operations can be assigned to tags using [OpenApiTag], this attribute allows you to:

  • Add descriptions that appear in documentation viewers
  • Link to external documentation for each tag
  • Define tags before they are used by operations

Examples​

Basic tag definition:

[assembly: OpenApiTagDefinition("Products", Description = "Operations for managing products")]

With external documentation:

[assembly: OpenApiTagDefinition("Orders", 
    Description = "Order management operations",
    ExternalDocsUrl = "https://docs.example.com/orders",
    ExternalDocsDescription = "Complete order API guide")]

Multiple tag definitions:

[assembly: OpenApiTagDefinition("Products", Description = "Product catalog operations")]
[assembly: OpenApiTagDefinition("Orders", Description = "Order management operations")]
[assembly: OpenApiTagDefinition("Admin", 
    Description = "Administrative operations",
    ExternalDocsUrl = "https://docs.example.com/admin")]

OpenApiTagGroupAttribute​

Groups related tags together for hierarchical navigation in documentation viewers. This attribute generates the x-tagGroups extension, which is supported by documentation tools like Redoc for organizing tags into collapsible sections.

Target: Assembly

Allow Multiple: Yes

Constructor Parameters​

ParameterTypeRequiredDescription
namestringYesThe display name of the tag group
tagsstring[]YesThe tag names to include in this group

Properties​

PropertyTypeDescription
NamestringGets the display name of the tag group
Tagsstring[]Gets the tag names included in this group

When to Use​

Use this attribute to organize your API documentation into logical sections when you have many tags. This is particularly useful for:

  • Large APIs with many endpoints across different domains
  • APIs that serve multiple user personas (admin, customer, partner)
  • Microservice-style APIs with distinct functional areas

Documentation tools like Redoc will display these groups as collapsible sections in the sidebar navigation.

Examples​

Basic tag grouping:

[assembly: OpenApiTagGroup("User Management", "Users", "Authentication", "Roles")]
[assembly: OpenApiTagGroup("Product Catalog", "Products", "Categories", "Inventory")]

E-commerce API organization:

// Define tags first
[assembly: OpenApiTagDefinition("Products", Description = "Product catalog operations")]
[assembly: OpenApiTagDefinition("Categories", Description = "Category management")]
[assembly: OpenApiTagDefinition("Orders", Description = "Order processing")]
[assembly: OpenApiTagDefinition("Payments", Description = "Payment operations")]
[assembly: OpenApiTagDefinition("Users", Description = "User management")]
[assembly: OpenApiTagDefinition("Admin", Description = "Administrative operations")]

// Group related tags
[assembly: OpenApiTagGroup("Catalog", "Products", "Categories")]
[assembly: OpenApiTagGroup("Commerce", "Orders", "Payments")]
[assembly: OpenApiTagGroup("Administration", "Users", "Admin")]

This generates the following x-tagGroups extension:

{
  "x-tagGroups": [
    {
      "name": "Catalog",
      "tags": ["Products", "Categories"]
    },
    {
      "name": "Commerce", 
      "tags": ["Orders", "Payments"]
    },
    {
      "name": "Administration",
      "tags": ["Users", "Admin"]
    }
  ]
}

OpenApiExternalDocsAttribute​

Specifies external documentation links for the API or individual operations. Can be applied at the assembly level for API-wide documentation or at the method level for operation-specific documentation.

Target: Assembly, Method

Constructor Parameters​

ParameterTypeRequiredDescription
urlstringYesThe URL for the external documentation

Properties​

PropertyTypeDefaultDescription
Urlstring—Gets the URL for the external documentation
DescriptionstringnullGets or sets a description of the external documentation

When to Use​

Use this attribute to link to external documentation resources:

  • Assembly level: Links to comprehensive API documentation, tutorials, or guides
  • Method level: Links to detailed documentation for specific operations

Examples​

Assembly-level (API-wide) documentation:

[assembly: OpenApiExternalDocs("https://docs.example.com/api", 
    Description = "Full API documentation and tutorials")]

Method-level (operation-specific) documentation:

[LambdaFunction]
[HttpApi(LambdaHttpMethod.Get, "/products/{id}")]
[OpenApiExternalDocs("https://docs.example.com/products/get-by-id", 
    Description = "Detailed guide for retrieving products")]
public Task<Product> GetProduct(string id)
{
    // Implementation
}

Combined usage:

// Assembly level - general API docs
[assembly: OpenApiExternalDocs("https://docs.example.com/api", Description = "API Reference")]

// Method level - specific operation docs
[OpenApiExternalDocs("https://docs.example.com/auth/oauth", Description = "OAuth flow guide")]
public Task<TokenResponse> GetToken([FromBody] TokenRequest request) { }

OpenApiExampleConfigAttribute​

Configures automatic example generation behavior for the OpenAPI specification. This attribute controls how examples are generated from property-level [OpenApiSchema] attributes.

Target: Assembly

Properties​

PropertyTypeDefaultDescription
ComposeFromPropertiesbooltrueWhen enabled, composes request/response examples from individual property Example values in [OpenApiSchema] attributes
GenerateDefaultsboolfalseWhen enabled, generates default example values for properties that don't have explicit examples

When to Use​

Use this attribute to control how examples appear in your generated OpenAPI specification:

  • Enable composition (default): Individual property examples from [OpenApiSchema(Example = "...")] are combined into complete request/response examples
  • Disable composition: Only explicit [OpenApiExample] attributes on methods generate examples
  • Generate defaults: Automatically create placeholder examples for properties without explicit values

Examples​

Default behavior (composition enabled):

[assembly: OpenApiExampleConfig(ComposeFromProperties = true)]

public class CreateProductRequest
{
    [OpenApiSchema(Description = "Product name", Example = "Widget Pro")]
    public string Name { get; set; }

    [OpenApiSchema(Description = "Price in USD", Example = "29.99")]
    public decimal Price { get; set; }
}

This automatically generates a composed example:

{
  "name": "Widget Pro",
  "price": 29.99
}

Disable automatic composition:

[assembly: OpenApiExampleConfig(ComposeFromProperties = false)]

With composition disabled, only explicit [OpenApiExample] attributes on methods will generate examples. Property-level examples in [OpenApiSchema] are still shown in the schema but won't be composed into request/response examples.

Enable default generation:

[assembly: OpenApiExampleConfig(ComposeFromProperties = true, GenerateDefaults = true)]

When GenerateDefaults is enabled, properties without explicit examples will receive type-appropriate placeholder values (e.g., "string" for strings, 0 for numbers).

Full control with explicit examples only:

// Disable automatic example generation
[assembly: OpenApiExampleConfig(ComposeFromProperties = false, GenerateDefaults = false)]

// Use explicit examples on methods instead
[LambdaFunction]
[HttpApi(LambdaHttpMethod.Post, "/products")]
[OpenApiExample("Create Product", 
    "{\"name\": \"Widget Pro\", \"price\": 29.99}", 
    IsRequestExample = true)]
public Task<Product> CreateProduct([FromBody] CreateProductRequest request)
{
    // Implementation
}

OpenApiResponseTypeAttribute​

Specifies the response type for a specific HTTP status code. Use this attribute to document actual response types when the method return type (e.g., IHttpResult) doesn't reflect the actual response body.

Target: Method

Allow Multiple: Yes

Constructor Parameters​

ParameterTypeRequiredDefaultDescription
responseTypeTypeYes—The type of the response body
statusCodeintNo200The HTTP status code this response applies to

Properties​

PropertyTypeDescription
ResponseTypeTypeGets the type of the response body
StatusCodeintGets the HTTP status code this response applies to
DescriptionstringGets or sets a description of the response

When to Use​

Use this attribute when your Lambda functions return IHttpResult or similar wrapper types that don't reflect the actual response body. Common scenarios:

  • Returning IHttpResult from Lambda Annotations
  • Using a service layer that wraps responses with status codes
  • Returning different types for different status codes

Without this attribute, methods returning IHttpResult will have no response schema documented.

Examples​

Basic usage with IHttpResult:

[LambdaFunction]
[HttpApi(LambdaHttpMethod.Post, "/products")]
[OpenApiResponseType(typeof(Product), 201, Description = "Returns the created product")]
public async Task<IHttpResult> CreateProduct([FromBody] CreateProductRequest request)
{
    var product = await _service.CreateProduct(request);
    return HttpResults.Created($"/products/{product.Id}", product);
}

Multiple response types:

[LambdaFunction]
[HttpApi(LambdaHttpMethod.Get, "/products/{id}")]
[OpenApiResponseType(typeof(Product), 200, Description = "Returns the product")]
[OpenApiResponseType(typeof(ErrorResponse), 404, Description = "Product not found")]
public async Task<IHttpResult> GetProduct(string id)
{
    var product = await _service.GetProduct(id);
    if (product == null)
        return HttpResults.NotFound(new ErrorResponse { Message = "Product not found" });
    return HttpResults.Ok(product);
}

With paginated responses:

[LambdaFunction]
[HttpApi(LambdaHttpMethod.Post, "/products/query")]
[OpenApiResponseType(typeof(PagedResult<Product>), 200, Description = "Returns paginated products")]
[OpenApiResponseType(typeof(ValidationError), 400, Description = "Invalid query parameters")]
public async Task<IHttpResult> QueryProducts([FromBody] QueryRequest request)
{
    // Implementation
}

Void response (no content):

[LambdaFunction]
[HttpApi(LambdaHttpMethod.Delete, "/products/{id}")]
[OpenApiResponseType(null, 204, Description = "Product deleted successfully")]
[OpenApiResponseType(typeof(ErrorResponse), 404, Description = "Product not found")]
public async Task<IHttpResult> DeleteProduct(string id)
{
    await _service.DeleteProduct(id);
    return HttpResults.NoContent();
}

Behavior​

When [OpenApiResponseType] attributes are present:

  • The generator uses these attributes to define response schemas
  • The method's return type is ignored for response documentation
  • Error responses (400, 401, 403, 500) are still added automatically unless explicitly specified

When no [OpenApiResponseType] attributes are present:

  • If the return type is IHttpResult or similar, no response schema is documented
  • Otherwise, the return type is used as the 200 response schema (with Task unwrapping)

OpenApiResponseHeaderAttribute​

Specifies response headers for an API operation. Use this attribute to document headers that are returned in API responses.

Target: Method

Allow Multiple: Yes

Constructor Parameters​

ParameterTypeRequiredDescription
namestringYesThe name of the response header

Properties​

PropertyTypeDefaultDescription
Namestring—Gets the name of the response header
StatusCodeint200Gets or sets the HTTP status code this header applies to
DescriptionstringnullGets or sets a description of the header
TypeTypetypeof(string)Gets or sets the type of the header value
RequiredboolfalseGets or sets whether the header is required

When to Use​

Use this attribute to document response headers that your API returns. This is useful for:

  • Pagination headers (X-Total-Count, X-Page-Size)
  • Rate limiting headers (X-Rate-Limit-Remaining)
  • Request tracking headers (X-Request-Id)
  • Custom application headers

Examples​

Basic header:

[LambdaFunction]
[HttpApi(LambdaHttpMethod.Get, "/products/{id}")]
[OpenApiResponseHeader("X-Request-Id", Description = "Unique request identifier for tracing")]
public Task<Product> GetProduct(string id)
{
    // Implementation
}

Multiple headers with types:

[LambdaFunction]
[HttpApi(LambdaHttpMethod.Get, "/products")]
[OpenApiResponseHeader("X-Total-Count", Description = "Total number of products", Type = typeof(int))]
[OpenApiResponseHeader("X-Page-Size", Description = "Number of products per page", Type = typeof(int))]
[OpenApiResponseHeader("X-Has-More", Description = "Whether more pages exist", Type = typeof(bool))]
public Task<IEnumerable<Product>> GetProducts([FromQuery] int page = 1)
{
    // Implementation
}

Headers for different status codes:

[LambdaFunction]
[HttpApi(LambdaHttpMethod.Post, "/products")]
[OpenApiResponseHeader("Location", StatusCode = 201, Description = "URL of the created resource")]
[OpenApiResponseHeader("X-Request-Id", StatusCode = 201, Description = "Request identifier")]
[OpenApiResponseHeader("Retry-After", StatusCode = 429, Description = "Seconds to wait before retrying", Type = typeof(int))]
public Task<Product> CreateProduct([FromBody] CreateProductRequest request)
{
    // Implementation
}

Required header:

[LambdaFunction]
[HttpApi(LambdaHttpMethod.Get, "/products")]
[OpenApiResponseHeader("X-Api-Version", Description = "API version", Required = true)]
public Task<IEnumerable<Product>> GetProducts()
{
    // Implementation
}

OpenApiExampleAttribute​

Specifies request or response examples for an API operation. Use this attribute to provide JSON examples that help API consumers understand expected payloads.

Target: Method

Allow Multiple: Yes

Constructor Parameters​

ParameterTypeRequiredDescription
namestringYesThe name of the example
valuestringYesThe JSON string value of the example

Properties​

PropertyTypeDefaultDescription
Namestring—Gets the name of the example
Valuestring—Gets the JSON string value of the example
StatusCodeint200Gets or sets the HTTP status code this example applies to (for response examples)
IsRequestExampleboolfalseGets or sets whether this is a request body example

When to Use​

Use this attribute to provide concrete examples of request and response payloads. Examples help API consumers:

  • Understand the expected data format
  • Test API calls with realistic data
  • Generate sample code in documentation tools

Examples​

Response example:

[LambdaFunction]
[HttpApi(LambdaHttpMethod.Get, "/products/{id}")]
[OpenApiExample("Single Product", 
    "{\"id\": \"123\", \"name\": \"Widget Pro\", \"price\": 29.99, \"category\": \"Electronics\"}", 
    StatusCode = 200)]
public Task<Product> GetProduct(string id)
{
    // Implementation
}

Request example:

[LambdaFunction]
[HttpApi(LambdaHttpMethod.Post, "/products")]
[OpenApiExample("Create Product Request", 
    "{\"name\": \"New Widget\", \"price\": 19.99, \"category\": \"Electronics\"}", 
    IsRequestExample = true)]
public Task<Product> CreateProduct([FromBody] CreateProductRequest request)
{
    // Implementation
}

Multiple examples:

[LambdaFunction]
[HttpApi(LambdaHttpMethod.Post, "/products")]
[OpenApiExample("Basic Product", 
    "{\"name\": \"Simple Widget\", \"price\": 9.99}", 
    IsRequestExample = true)]
[OpenApiExample("Full Product", 
    "{\"name\": \"Premium Widget\", \"price\": 49.99, \"category\": \"Premium\", \"description\": \"High-end widget\"}", 
    IsRequestExample = true)]
[OpenApiExample("Created Response", 
    "{\"id\": \"456\", \"name\": \"Simple Widget\", \"price\": 9.99}", 
    StatusCode = 200)]
public Task<Product> CreateProduct([FromBody] CreateProductRequest request)
{
    // Implementation
}

Examples for different status codes:

[LambdaFunction]
[HttpApi(LambdaHttpMethod.Get, "/products/{id}")]
[OpenApiResponseType(typeof(Product), 200)]
[OpenApiResponseType(typeof(ErrorResponse), 404)]
[OpenApiExample("Found Product", 
    "{\"id\": \"123\", \"name\": \"Widget\"}", 
    StatusCode = 200)]
[OpenApiExample("Not Found Error", 
    "{\"message\": \"Product not found\", \"errorCode\": \"PRODUCT_NOT_FOUND\"}", 
    StatusCode = 404)]
public Task<IHttpResult> GetProduct(string id)
{
    // Implementation
}

OpenApiOperationAttribute​

Adds metadata to API operations including summary, description, deprecation status, and operation ID.

Target: Method

Properties​

PropertyTypeDefaultDescription
SummarystringnullShort summary displayed as the operation title
DescriptionstringnullDetailed explanation (supports markdown)
DeprecatedboolfalseMarks the operation as deprecated. Can also be set using [Obsolete].
OperationIdstringnullA custom operation ID for code generation. If not specified, generated from method name.

Deprecation​

Operations can be marked as deprecated in two ways:

  • Using [OpenApiOperation(Deprecated = true)]
  • Using the standard [Obsolete] attribute (which also captures the deprecation message)

Both approaches work, and can be combined. The [Obsolete] attribute is recommended when you also want compiler warnings.

Examples​

Basic usage:

[LambdaFunction]
[HttpApi(LambdaHttpMethod.Get, "/products/{id}")]
[OpenApiOperation(
    Summary = "Get product by ID",
    Description = "Retrieves a single product by its unique identifier. Returns 404 if not found.")]
public Task<Product> GetProduct(string id)
{
    // Implementation
}

With operation ID:

[LambdaFunction]
[HttpApi(LambdaHttpMethod.Get, "/products")]
[OpenApiOperation(
    Summary = "List all products",
    OperationId = "listAllProducts")]
public Task<IEnumerable<Product>> GetProducts()
{
    // Implementation
}

Deprecated operation:

[LambdaFunction]
[HttpApi(LambdaHttpMethod.Get, "/products/legacy")]
[OpenApiOperation(
    Summary = "Legacy product list",
    Description = "This endpoint is deprecated. Use GET /products instead.",
    Deprecated = true)]
public Task<IEnumerable<Product>> GetProductsLegacy()
{
    // Implementation
}

// Or using [Obsolete] for compiler warnings too:
[LambdaFunction]
[HttpApi(LambdaHttpMethod.Get, "/products/old")]
[Obsolete("Use GET /products instead")]
public Task<IEnumerable<Product>> GetProductsOld()
{
    // Implementation
}

OpenApiOperationIdAttribute​

Specifies a custom operation ID for an API operation. Operation IDs are used by code generators to create meaningful method names in client SDKs.

Target: Method

Constructor Parameters​

ParameterTypeRequiredDescription
operationIdstringYesThe custom operation ID

Properties​

PropertyTypeDescription
OperationIdstringGets the custom operation ID

When to Use​

Use this attribute when you want to:

  • Override the auto-generated operation ID (which defaults to the method name)
  • Ensure consistent naming across API versions
  • Follow specific naming conventions for client SDK generation

Without this attribute, the generator creates operation IDs based on the method name and ensures uniqueness by appending numeric suffixes if needed.

Examples​

Basic usage:

[LambdaFunction]
[HttpApi(LambdaHttpMethod.Get, "/products")]
[OpenApiOperationId("listAllProducts")]
public Task<IEnumerable<Product>> GetProducts()
{
    // Implementation
}

RESTful naming convention:

[LambdaFunction]
[HttpApi(LambdaHttpMethod.Get, "/products/{id}")]
[OpenApiOperationId("getProductById")]
public Task<Product> GetProduct(string id) { }

[LambdaFunction]
[HttpApi(LambdaHttpMethod.Post, "/products")]
[OpenApiOperationId("createProduct")]
public Task<Product> CreateProduct([FromBody] CreateProductRequest request) { }

[LambdaFunction]
[HttpApi(LambdaHttpMethod.Put, "/products/{id}")]
[OpenApiOperationId("updateProduct")]
public Task<Product> UpdateProduct(string id, [FromBody] UpdateProductRequest request) { }

[LambdaFunction]
[HttpApi(LambdaHttpMethod.Delete, "/products/{id}")]
[OpenApiOperationId("deleteProduct")]
public Task DeleteProduct(string id) { }

OpenApiTagAttribute​

Groups operations by tags for better organization in the generated documentation.

Target: Class, Method, Parameter, Property

Parameters​

ParameterTypeRequiredDefaultDescription
tagstringYes—The tag name for grouping
descriptionstringNonullOptional tag description

Example​

// Class-level tag — all methods inherit this tag
[OpenApiTag("Products", "Operations for managing products")]
public class ProductFunctions
{
    [LambdaFunction]
    [HttpApi(LambdaHttpMethod.Get, "/products")]
    public Task<IEnumerable<Product>> GetProducts() { }

    [LambdaFunction]
    [HttpApi(LambdaHttpMethod.Post, "/products")]
    public Task<Product> CreateProduct([FromBody] CreateProductRequest request) { }
}

// Method-level tag
public class OrderFunctions
{
    [LambdaFunction]
    [HttpApi(LambdaHttpMethod.Get, "/orders")]
    [OpenApiTag("Orders", "Operations for managing orders")]
    public Task<IEnumerable<Order>> GetOrders() { }

    [LambdaFunction]
    [HttpApi(LambdaHttpMethod.Get, "/orders/{id}/items")]
    [OpenApiTag("Order Items")]
    public Task<IEnumerable<OrderItem>> GetOrderItems(string id) { }
}

OpenApiSchemaAttribute​

Customizes schema information for properties and parameters, including validation rules, formats, and examples.

Target: Property, Parameter

Properties​

PropertyTypeDefaultDescription
DescriptionstringnullProperty description
FormatstringnullFormat hint (e.g., "date-time", "email", "uuid")
ExamplestringnullExample value
PatternstringnullRegex pattern for validation
Minimumdouble0Minimum value for numbers
Maximumdouble0Maximum value for numbers
ExclusiveMinimumboolfalseWhether minimum is exclusive
ExclusiveMaximumboolfalseWhether maximum is exclusive
MinLengthint0Minimum string length
MaxLengthint0Maximum string length

Examples​

Basic property documentation:

public class Product
{
    [OpenApiSchema(Description = "Unique product identifier", Format = "uuid")]
    public string Id { get; set; }

    [OpenApiSchema(Description = "Product name", MinLength = 1, MaxLength = 200)]
    public string Name { get; set; }

    [OpenApiSchema(Description = "Price in USD", Minimum = 0)]
    public decimal Price { get; set; }
}

Request model with examples:

public class CreateProductRequest
{
    [OpenApiSchema(
        Description = "Product name",
        MinLength = 1,
        MaxLength = 200,
        Example = "Widget Pro")]
    public string Name { get; set; }

    [OpenApiSchema(
        Description = "Price in USD",
        Minimum = 0.01,
        Example = "29.99")]
    public decimal Price { get; set; }

    [OpenApiSchema(
        Description = "Product category",
        Example = "Electronics")]
    public string Category { get; set; }
}

Pattern validation:

public class User
{
    [OpenApiSchema(
        Description = "Email address",
        Format = "email",
        Pattern = @"^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$")]
    public string Email { get; set; }

    [OpenApiSchema(
        Description = "Phone in E.164 format",
        Pattern = @"^\+[1-9]\d{1,14}$",
        Example = "+14155551234")]
    public string PhoneNumber { get; set; }
}

Numeric constraints:

public class PaginationRequest
{
    [OpenApiSchema(Description = "Page number (1-based)", Minimum = 1, Example = "1")]
    public int Page { get; set; }

    [OpenApiSchema(Description = "Items per page", Minimum = 1, Maximum = 100, Example = "20")]
    public int PageSize { get; set; }
}

OpenApiIgnoreAttribute​

Excludes properties or parameters from the generated OpenAPI documentation.

Target: Parameter, Property

When to Use​

  • Internal tracking fields (timestamps, audit fields)
  • Implementation details not part of the public API
  • System-populated properties
  • Sensitive fields that shouldn't be documented

Example​

public class Product
{
    [OpenApiSchema(Description = "Unique product identifier")]
    public string Id { get; set; }

    [OpenApiSchema(Description = "Product name")]
    public string Name { get; set; }

    // Excluded from OpenAPI schema
    [OpenApiIgnore]
    public DateTime InternalCreatedAt { get; set; }

    [OpenApiIgnore]
    public string LastModifiedBy { get; set; }
}

Ignoring method parameters:

[LambdaFunction]
[HttpApi(LambdaHttpMethod.Get, "/products")]
public Task<IEnumerable<Product>> GetProducts(
    [FromQuery] int limit,
    [FromQuery] string category,
    [OpenApiIgnore] ILambdaContext context) // Lambda context excluded
{
    // Implementation
}

OpenApiOutputAttribute​

Configures the output location for the generated OpenAPI specification. Apply at the assembly level.

Target: Assembly

Parameters​

ParameterTypeRequiredDescription
specificationstringYesSpecification name (matches API title)
outputPathstringYesFile path for the generated spec

Example​

// In AssemblyInfo.cs or any .cs file
using Oproto.Lambda.OpenApi.Attributes;

[assembly: OpenApiOutput("Products API", "docs/api/openapi.json")]

Multiple specifications:

[assembly: OpenApiOutput("Products API", "docs/products-api.json")]
[assembly: OpenApiOutput("Orders API", "docs/orders-api.json")]

Deprecation Support​

The generator automatically detects the standard .NET [Obsolete] attribute and marks operations as deprecated in the OpenAPI specification.

Behavior​

  • When a method has [Obsolete], the operation's deprecated field is set to true
  • When [Obsolete] includes a message, that message is appended to the operation description
  • Methods without [Obsolete] do not include the deprecated field

Example​

[LambdaFunction]
[HttpApi(LambdaHttpMethod.Delete, "/products/{id}")]
[OpenApiOperation(Summary = "Delete a product")]
[Obsolete("Use the archive endpoint instead. This endpoint will be removed in v2.0.")]
public Task DeleteProduct(string id)
{
    // Implementation
}

This generates:

{
  "delete": {
    "summary": "Delete a product",
    "description": "Deprecated: Use the archive endpoint instead. This endpoint will be removed in v2.0.",
    "deprecated": true
  }
}

See Also​