tessl/nuget-nswag

The OpenAPI/Swagger API toolchain for .NET and TypeScript

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Core Document Model

Name: tessl/nuget-nswag
Author: tessl

The core document model provides the fundamental classes for representing OpenAPI/Swagger specifications in .NET. These classes form the foundation of the NSwag toolchain.

OpenApiDocument

The main document class representing a complete OpenAPI/Swagger specification.

public partial class OpenApiDocument : JsonExtensionObject, IDocumentPathProvider
{
    // Core properties
    public string Swagger { get; set; }
    public string OpenApi { get; set; }
    public OpenApiInfo Info { get; set; }
    public IDictionary<string, OpenApiPathItem> Paths { get; }
    public OpenApiComponents Components { get; set; }
    public IList<OpenApiServer> Servers { get; set; }
    public IList<OpenApiSecurityRequirement> Security { get; set; }
    public IList<OpenApiTag> Tags { get; set; }
    public OpenApiExternalDocumentation ExternalDocumentation { get; set; }
    
    // Document operations
    public static Task<OpenApiDocument> FromFileAsync(string filePath);
    public static Task<OpenApiDocument> FromJsonAsync(string json);
    public static Task<OpenApiDocument> FromUrlAsync(string url);
    public string ToJson();
    public Task<string> ToYamlAsync();
    public void GenerateOperationIds();
    
    // Utility properties
    public static string ToolchainVersion { get; }
    public string DocumentPath { get; set; }
}

Usage Examples

// Load from file
var document = await OpenApiDocument.FromFileAsync("swagger.json");

// Load from URL
var document = await OpenApiDocument.FromUrlAsync("https://api.example.com/swagger.json");

// Create new document
var document = new OpenApiDocument
{
    Info = new OpenApiInfo
    {
        Title = "My API",
        Version = "1.0.0"
    }
};

// Generate operation IDs
document.GenerateOperationIds();

// Serialize to JSON
string json = document.ToJson();

OpenApiOperation

Represents a single API operation (HTTP method on a path).

public class OpenApiOperation : JsonExtensionObject
{
    public IList<string> Tags { get; set; }
    public string Summary { get; set; }
    public string Description { get; set; }
    public string OperationId { get; set; }
    public IList<OpenApiParameter> Parameters { get; }
    public OpenApiRequestBody RequestBody { get; set; }
    public IDictionary<string, OpenApiResponse> Responses { get; }
    public bool Deprecated { get; set; }
    public IList<OpenApiSecurityRequirement> Security { get; set; }
    public IList<OpenApiServer> Servers { get; set; }
    public OpenApiExternalDocumentation ExternalDocumentation { get; set; }
    public IDictionary<string, OpenApiCallback> Callbacks { get; set; }
    
    // Parameter management
    public OpenApiParameter GetParameter(string name, OpenApiParameterKind kind);
    public bool HasParameter(string name, OpenApiParameterKind kind);
    public void AddParameter(OpenApiParameter parameter);
    public void RemoveParameter(string name, OpenApiParameterKind kind);
}

OpenApiParameter

Represents a parameter in an OpenAPI operation.

public class OpenApiParameter : JsonSchema
{
    public string Name { get; set; }
    public OpenApiParameterKind Kind { get; set; }
    public OpenApiParameterStyle Style { get; set; }
    public bool Explode { get; set; }
    public bool AllowReserved { get; set; }
    public JsonSchema Schema { get; set; }
    public object Example { get; set; }
    public IDictionary<string, OpenApiExample> Examples { get; set; }
    public IDictionary<string, OpenApiMediaType> Content { get; set; }
    
    // Legacy Swagger 2.0 properties
    public OpenApiParameterCollectionFormat CollectionFormat { get; set; }
    public string Format { get; set; }
    public bool AllowEmptyValue { get; set; }
}

OpenApiResponse

Represents a response from an API operation.

public class OpenApiResponse : JsonExtensionObject
{
    public string Description { get; set; }
    public IDictionary<string, OpenApiHeader> Headers { get; set; }
    public IDictionary<string, OpenApiMediaType> Content { get; set; }
    public IDictionary<string, OpenApiLink> Links { get; set; }
    
    // Legacy Swagger 2.0 properties
    public JsonSchema Schema { get; set; }
    public IDictionary<string, JsonSchema> Examples { get; set; }
}

OpenApiInfo

Contains metadata about the API.

public class OpenApiInfo : JsonExtensionObject
{
    public string Title { get; set; }
    public string Description { get; set; }
    public string Version { get; set; }
    public string TermsOfService { get; set; }
    public OpenApiContact Contact { get; set; }
    public OpenApiLicense License { get; set; }
}

OpenApiServer

Represents a server where the API is hosted (OpenAPI 3.0).

public class OpenApiServer : JsonExtensionObject
{
    public string Url { get; set; }
    public string Description { get; set; }
    public IDictionary<string, OpenApiServerVariable> Variables { get; set; }
}

OpenApiComponents

Container for reusable components in OpenAPI 3.0.

public class OpenApiComponents : JsonExtensionObject
{
    public IDictionary<string, JsonSchema> Schemas { get; set; }
    public IDictionary<string, OpenApiResponse> Responses { get; set; }
    public IDictionary<string, OpenApiParameter> Parameters { get; set; }
    public IDictionary<string, OpenApiExample> Examples { get; set; }
    public IDictionary<string, OpenApiRequestBody> RequestBodies { get; set; }
    public IDictionary<string, OpenApiHeader> Headers { get; set; }
    public IDictionary<string, OpenApiSecurityScheme> SecuritySchemes { get; set; }
    public IDictionary<string, OpenApiLink> Links { get; set; }
    public IDictionary<string, OpenApiCallback> Callbacks { get; set; }
}

OpenApiSecurityScheme

Defines a security scheme for the API.

public class OpenApiSecurityScheme : JsonExtensionObject
{
    public OpenApiSecuritySchemeType Type { get; set; }
    public string Description { get; set; }
    public string Name { get; set; }
    public OpenApiSecurityApiKeyLocation In { get; set; }
    public string Scheme { get; set; }
    public string BearerFormat { get; set; }
    public OpenApiOAuthFlows Flows { get; set; }
    public string OpenIdConnectUrl { get; set; }
}

Supporting Types

OpenApiPathItem

public class OpenApiPathItem : JsonExtensionObject
{
    public string Summary { get; set; }
    public string Description { get; set; }
    public OpenApiOperation Get { get; set; }
    public OpenApiOperation Put { get; set; }
    public OpenApiOperation Post { get; set; }
    public OpenApiOperation Delete { get; set; }
    public OpenApiOperation Options { get; set; }
    public OpenApiOperation Head { get; set; }
    public OpenApiOperation Patch { get; set; }
    public OpenApiOperation Trace { get; set; }
    public IList<OpenApiServer> Servers { get; set; }
    public IList<OpenApiParameter> Parameters { get; }
}

OpenApiTag

public class OpenApiTag : JsonExtensionObject
{
    public string Name { get; set; }
    public string Description { get; set; }
    public OpenApiExternalDocumentation ExternalDocumentation { get; set; }
}

OpenApiContact

public class OpenApiContact : JsonExtensionObject
{
    public string Name { get; set; }
    public string Url { get; set; }
    public string Email { get; set; }
}

OpenApiLicense

public class OpenApiLicense : JsonExtensionObject
{
    public string Name { get; set; }
    public string Url { get; set; }
}

Enumerations

OpenApiParameterKind

public enum OpenApiParameterKind
{
    Undefined,
    Body,
    Query,
    Path,
    Header,
    FormData,
    ModelBinding,
    Cookie
}

OpenApiParameterStyle

public enum OpenApiParameterStyle
{
    Matrix,
    Label,
    Form,
    Simple,
    SpaceDelimited,
    PipeDelimited,
    DeepObject
}

OpenApiParameterCollectionFormat

public enum OpenApiParameterCollectionFormat
{
    Undefined,
    Csv,
    Ssv,
    Tsv,
    Pipes,
    Multi
}

OpenApiSecuritySchemeType

public enum OpenApiSecuritySchemeType
{
    Undefined,
    Basic,
    ApiKey,
    OAuth2,
    OpenIdConnect
}

OpenApiSecurityApiKeyLocation

public enum OpenApiSecurityApiKeyLocation
{
    Undefined,
    Query,
    Header,
    Cookie
}

HTTP Method Constants

public static class OpenApiOperationMethod
{
    public const string Get = "get";
    public const string Post = "post";
    public const string Put = "put";
    public const string Delete = "delete";
    public const string Options = "options";
    public const string Head = "head";
    public const string Patch = "patch";
    public const string Trace = "trace";
}