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

NSwag

Name: tessl/nuget-nswag
Author: tessl

NSwag is a comprehensive OpenAPI/Swagger toolchain for .NET, ASP.NET Core, and TypeScript that combines the functionality of Swashbuckle (OpenAPI/Swagger generation) and AutoRest (client generation) into a unified solution. The library enables developers to generate OpenAPI 2.0 and 3.0 specifications from C# ASP.NET (Core) controllers, serve these specifications via middleware with optional Swagger UI or ReDoc integration, and generate strongly-typed C# or TypeScript client proxies from the specifications.

Package Information

Package Name: NSwag.Core (and related packages)
Package Type: NuGet
Language: C#
Installation: dotnet add package NSwag.Core (for core functionality), dotnet add package NSwag.AspNetCore (for ASP.NET Core integration)

Core Imports

using NSwag;
using NSwag.Generation;
using NSwag.Generation.AspNetCore;
using NSwag.CodeGeneration.CSharp;
using NSwag.CodeGeneration.TypeScript;

For ASP.NET Core integration:

using NSwag.AspNetCore;

Basic Usage

Document Generation from ASP.NET Core

using NSwag.Generation.AspNetCore;

// Create settings
var settings = new AspNetCoreOpenApiDocumentGeneratorSettings
{
    Title = "My API",
    Version = "1.0.0"
};

// Generate document
var generator = new AspNetCoreOpenApiDocumentGenerator(settings);
var document = await generator.GenerateAsync("v1");

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

ASP.NET Core Middleware Integration

// In Program.cs or Startup.cs
services.AddOpenApiDocument(config =>
{
    config.Title = "My API";
    config.Version = "v1";
});

app.UseOpenApi(); // Serves the OpenAPI specification
app.UseSwaggerUi3(); // Serves Swagger UI

Client Generation

using NSwag.CodeGeneration.CSharp;

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

// Configure client generation
var settings = new CSharpClientGeneratorSettings
{
    ClassName = "MyApiClient",
    Namespace = "MyApp.ApiClients"
};

// Generate client code
var generator = new CSharpClientGenerator(document, settings);
string clientCode = generator.GenerateFile();

Architecture

NSwag is built around several key components:

Core Models: OpenAPI document object model (NSwag.Core)
Generation Framework: Extensible document generation system (NSwag.Generation)
Code Generators: Client and controller code generation (NSwag.CodeGeneration.*)
ASP.NET Integration: Middleware and services for web applications (NSwag.AspNetCore)
Annotations: Attributes for customizing OpenAPI generation (NSwag.Annotations)
CLI Tools: Command-line utilities for automation (NSwag.Commands)

Capabilities

Core OpenAPI Document Model

Core classes and interfaces for representing OpenAPI/Swagger specifications.

public partial class OpenApiDocument : JsonExtensionObject, IDocumentPathProvider
{
    public OpenApiInfo Info { get; set; }
    public IDictionary<string, OpenApiPathItem> Paths { get; }
    public OpenApiComponents Components { get; set; }
    public IList<OpenApiServer> Servers { get; set; }
    public IList<OpenApiTag> Tags { get; set; }
    
    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 void GenerateOperationIds();
}

Core Document Model

Document Generation

Framework for generating OpenAPI documents from .NET applications.

public interface IOpenApiDocumentGenerator
{
    Task<OpenApiDocument> GenerateAsync(string documentName);
}

public class AspNetCoreOpenApiDocumentGenerator : IOpenApiDocumentGenerator
{
    public AspNetCoreOpenApiDocumentGenerator(AspNetCoreOpenApiDocumentGeneratorSettings settings);
    public Task<OpenApiDocument> GenerateAsync(string documentName);
}

Document Generation

C# Client Generation

Generate strongly-typed C# client proxies from OpenAPI specifications.

public class CSharpClientGenerator : CSharpGeneratorBase
{
    public CSharpClientGenerator(OpenApiDocument document, CSharpClientGeneratorSettings settings);
    public CSharpClientGenerator(OpenApiDocument document, CSharpClientGeneratorSettings settings, CSharpTypeResolver resolver);
    public string GenerateFile();
    public string GenerateFile(ClientGeneratorOutputType outputType);
}

C# Client Generation

TypeScript Client Generation

Generate TypeScript client code from OpenAPI specifications.

public class TypeScriptClientGenerator : ClientGeneratorBase<TypeScriptClientGeneratorSettings>
{
    public TypeScriptClientGenerator(OpenApiDocument document, TypeScriptClientGeneratorSettings settings);
    public string GenerateFile();
}

TypeScript Client Generation

ASP.NET Core Integration

Middleware and services for integrating OpenAPI generation and UI into ASP.NET Core applications.

public static class NSwagServiceCollectionExtensions
{
    public static IServiceCollection AddOpenApiDocument(this IServiceCollection services);
    public static IServiceCollection AddOpenApiDocument(this IServiceCollection services, Action<AspNetCoreOpenApiDocumentGeneratorSettings> configure);
    public static IServiceCollection AddSwaggerDocument(this IServiceCollection services);
}

public static class NSwagApplicationBuilderExtensions
{
    public static IApplicationBuilder UseOpenApi(this IApplicationBuilder app);
    public static IApplicationBuilder UseSwaggerUi3(this IApplicationBuilder app);
    public static IApplicationBuilder UseReDoc(this IApplicationBuilder app);
}

ASP.NET Core Integration

Annotations

Attributes for customizing OpenAPI generation behavior.

[AttributeUsage(AttributeTargets.Method)]
public class OpenApiOperationAttribute : Attribute
{
    public OpenApiOperationAttribute(string operationId);
    public OpenApiOperationAttribute(string summary, string description);
    public OpenApiOperationAttribute(string operationId, string summary, string description);
    
    public string Summary { get; }
    public string Description { get; }
}

[AttributeUsage(AttributeTargets.Class | AttributeTargets.Method, AllowMultiple = true)]
public class OpenApiTagAttribute : Attribute
{
    public OpenApiTagAttribute(string name);
    
    public string Name { get; set; }
    public string Description { get; set; }
    public string DocumentationDescription { get; set; }
    public string DocumentationUrl { get; set; }
    public bool AddToDocument { get; set; }
}

Annotations

CLI Commands

Command-line tools for code generation and document processing.

public class OpenApiToCSharpClientCommand : OutputCommandBase
{
    public CSharpClientGeneratorSettings Settings { get; set; }
    public string Input { get; set; }
    public string Output { get; set; }
    
    public Task<object> RunAsync();
}

CLI Commands

Types

Core Interfaces

public interface IDocumentPathProvider
{
    string DocumentPath { get; set; }
}

public interface IOpenApiDocumentGenerator
{
    Task<OpenApiDocument> GenerateAsync(string documentName);
}

public interface IClientGenerator
{
    string GetTypeName(JsonSchema schema, bool isNullable, string typeNameHint);
    string GetBinaryResponseTypeName();
}

Base Classes

public abstract class ClientGeneratorBase<TSettings> : IClientGenerator
    where TSettings : ClientGeneratorBaseSettings
{
    protected ClientGeneratorBase(OpenApiDocument document, TSettings settings);
    public abstract string GenerateFile();
    public string GetTypeName(JsonSchema schema, bool isNullable, string typeNameHint);
    public string GetBinaryResponseTypeName();
}

public abstract class ClientGeneratorBaseSettings : CodeGeneratorSettingsBase
{
    public string ClassName { get; set; }
    public bool GenerateClientClasses { get; set; }
    public bool GenerateClientInterfaces { get; set; }
    public bool InjectHttpClient { get; set; }
}

Enumerations

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

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

public enum ClientGeneratorOutputType
{
    Full,
    Implementation,
    Contracts
}

Workspace: tessl
Visibility: Public
Created: 6 months ago
Last updated: about 1 month ago
Describes: pkg:nuget/NSwag.Core@13.20.x
Publish Source: CLI
Badge