.NET ヘルプ

Nswag C#（開発者向けの動作方法）

公開済み 2024年6月6日

共有:

イントロダクション

APIは今日のソフトウェア開発環境において不可欠であり、様々なソフトウェアシステムおよびコンポーネント間の通信を容易にします。開発者がAPIを効率的に使用するためには、徹底的で理解しやすいドキュメントが必要です。 C# APIドキュメントのワークフローに役立つ2つの効果的なツールは、NSwag C#とIronPDFです。この記事では、NSwagを使用して生成する方法について説明します。API仕様.NET Coreを使用し、IronPDFを使用してこれらの仕様から高品質のPDFドキュメントを作成します。

C#でNSwagを使用する方法

Swagger UIを使用してRESTful Web APIを作成します。
C#コンソールアプリケーションを作成します。
NSwagライブラリをインストールします。
名前空間をインポートし、オブジェクトを作成します。
Swagger JSONをC#コードに処理する。
コードを実行して結果を表示します。

NSwagを理解する

NSwagと呼ばれる.NET Swaggerツールチェーンは、ASP.NET Web API、ASP.NET Core、または他の.NET Frameworkを使用して構築されたAPI用のSwagger仕様、またはOpenAPIドキュメントを簡単に作成できるように作成されました。

NSwagの機能

Swagger仕様の生成

コントローラー、モデル、および.NETアセンブリはすべて、NSwagによって自動的にSwagger仕様を生成するために使用できます。 NSwagは、APIコードの構造を調査することにより、APIエンドポイント、リクエスト/レスポンス形式、認証技術などをカバーする包括的なドキュメントを生成します。

.NETプロジェクトへの接続

開発者は、NSwagを.NETプロジェクトに統合することで、開発プロセスにSwagger生成を簡単に組み込むことができます。開発者は、.NET CoreプロジェクトにNSwagを追加することで、プロジェクトがビルドされるたびに自動的にSwagger仕様が生成され、ドキュメントがコードベースとともに更新されるようにすることができます。

パーソナライゼーションと拡張

NSwagが提供する幅広いカスタマイズの可能性により、開発者は生成されたSwagger仕様を簡単に自分のニーズに合わせて適応させることができます。開発者は、設定およびアノテーションを通じて、生成されたドキュメントのレスポンスコード、パラメータの説明、ルート命名規則などの多くのコンポーネントを制御することができます。

NSwagを使い始める

C#コンソールアプリでのNSwagのセットアップ

NSwag基本クラスライブラリには、コア、アノテーション、コード生成名前空間が含まれており、NuGetからインストールすることで利用できるようになります。 NSwagをC#アプリケーションに統合してコードとSwagger仕様を生成する方法、およびNSwagが開発プロセスの効率をどのように向上させるかについて。

NSwag C#（開発者のための仕組み）：図1 - Visual StudioパッケージマネージャでNSwagを参照し、インストールする。

WindowsコンソールとフォームでのNSwagの実装

自動化されたクライアント生成を通じて、開発者はNSwagをWindowsデスクトップアプリケーションに統合することにより、デスクトップアプリ内からAPIにアクセスするためのコードを効率的に生成することができます。オンライン・サービスやRESTful APIと通信するデスクトップ・アプリケーションを開発する場合、かなり役立ちます。

NSwagは、Webアプリケーションで内部APIのAPIドキュメントを生成し、外部APIを消費するためのクライアントコードを生成するために使用できます。これは、開発者がアプリケーションのフロントエンドとバックエンドコンポーネントを一貫して保つのに役立ちます。

NSwag C#の例

以下は、NSwagを使用してC#クライアントコードを生成する方法を示すコードの例です：

using NSwag.CodeGeneration.CSharp;
using NSwag;
using System.Reflection;
using System.CodeDom.Compiler;
using Microsoft.CodeAnalysis;
class Program
{
    static async Task Main(string[] args)
    {
        System.Net.WebClient wclient = new System.Net.WebClient();
        // Create JSON file data from the Swagger net core web API
        var document = await OpenApiDocument.FromJsonAsync(wclient.DownloadString("http://localhost:5013/swagger/v1/swagger.json"));
        wclient.Dispose();
        var settings = new CSharpClientGeneratorSettings
        {
            ClassName = "Weather",
            CSharpGeneratorSettings =
    {
        Namespace = "Demo"
    }
        };
        var generator = new CSharpClientGenerator(document, settings);
        var code = generator.GenerateFile();
        var assembly = CompileCode(code);
        var clientType = assembly.GetType("Demo.WeatherClient"); // Replace with your actual client class name
        var httpClient = new HttpClient();
        var client = (IApiClient)Activator.CreateInstance(clientType, httpClient);
        var result = await client.GetWeatherForecastAsync();
        foreach (var item in result)
        {
            Console.WriteLine($"Date: {item.Date} F: {item.TemperatureF} C: {item.TemperatureC} Summary: {item.Summary}");
        }
    }
    static Assembly CompileCode(string code)
    {
        using (var memoryStream = new MemoryStream())
        {
            var assemblyPath = Path.GetDirectoryName(typeof(object).Assembly.Location);
            List<MetadataReference> references = new List<MetadataReference>();
            references.Add(MetadataReference.CreateFromFile(typeof(object).GetTypeInfo().Assembly.Location));
            references.Add(MetadataReference.CreateFromFile(Path.Combine(assemblyPath, "Microsoft.AspNetCore.Mvc.dll")));
            references.Add(MetadataReference.CreateFromFile(Path.Combine(assemblyPath, "System.Web.Http.dll")));
            var compilation = Microsoft.CodeAnalysis.CSharp.CSharpCompilation.Create("ApiClient")
                .AddReferences(Microsoft.CodeAnalysis.MetadataReference.CreateFromFile(typeof(object).Assembly.Location))
                .AddSyntaxTrees(Microsoft.CodeAnalysis.CSharp.SyntaxFactory.ParseSyntaxTree(code)).AddReferences(references);
            var emitResult = compilation.Emit(memoryStream);
            if (!emitResult.Success)
            {
                var diagnostics = emitResult.Diagnostics;
                Console.WriteLine("Compilation errors:");
                foreach (var diagnostic in diagnostics)
                {
                    Console.WriteLine(diagnostic);
                }
                return null;
            }
            memoryStream.Seek(0, SeekOrigin.Begin);
            return Assembly.Load(memoryStream.ToArray());
        }
    }
    public interface IApiClient
    {
        Task<List<WeatherForecast>> GetWeatherForecastAsync(); // Replace with your actual method name and return type
    }
    public class WeatherForecast
    {
        public DateTime Date { get; set; }
        public int TemperatureC { get; set; }
        public int TemperatureF { get; set; }
        public string Summary { get; set; }
    }
}

using NSwag.CodeGeneration.CSharp;
using NSwag;
using System.Reflection;
using System.CodeDom.Compiler;
using Microsoft.CodeAnalysis;
class Program
{
    static async Task Main(string[] args)
    {
        System.Net.WebClient wclient = new System.Net.WebClient();
        // Create JSON file data from the Swagger net core web API
        var document = await OpenApiDocument.FromJsonAsync(wclient.DownloadString("http://localhost:5013/swagger/v1/swagger.json"));
        wclient.Dispose();
        var settings = new CSharpClientGeneratorSettings
        {
            ClassName = "Weather",
            CSharpGeneratorSettings =
    {
        Namespace = "Demo"
    }
        };
        var generator = new CSharpClientGenerator(document, settings);
        var code = generator.GenerateFile();
        var assembly = CompileCode(code);
        var clientType = assembly.GetType("Demo.WeatherClient"); // Replace with your actual client class name
        var httpClient = new HttpClient();
        var client = (IApiClient)Activator.CreateInstance(clientType, httpClient);
        var result = await client.GetWeatherForecastAsync();
        foreach (var item in result)
        {
            Console.WriteLine($"Date: {item.Date} F: {item.TemperatureF} C: {item.TemperatureC} Summary: {item.Summary}");
        }
    }
    static Assembly CompileCode(string code)
    {
        using (var memoryStream = new MemoryStream())
        {
            var assemblyPath = Path.GetDirectoryName(typeof(object).Assembly.Location);
            List<MetadataReference> references = new List<MetadataReference>();
            references.Add(MetadataReference.CreateFromFile(typeof(object).GetTypeInfo().Assembly.Location));
            references.Add(MetadataReference.CreateFromFile(Path.Combine(assemblyPath, "Microsoft.AspNetCore.Mvc.dll")));
            references.Add(MetadataReference.CreateFromFile(Path.Combine(assemblyPath, "System.Web.Http.dll")));
            var compilation = Microsoft.CodeAnalysis.CSharp.CSharpCompilation.Create("ApiClient")
                .AddReferences(Microsoft.CodeAnalysis.MetadataReference.CreateFromFile(typeof(object).Assembly.Location))
                .AddSyntaxTrees(Microsoft.CodeAnalysis.CSharp.SyntaxFactory.ParseSyntaxTree(code)).AddReferences(references);
            var emitResult = compilation.Emit(memoryStream);
            if (!emitResult.Success)
            {
                var diagnostics = emitResult.Diagnostics;
                Console.WriteLine("Compilation errors:");
                foreach (var diagnostic in diagnostics)
                {
                    Console.WriteLine(diagnostic);
                }
                return null;
            }
            memoryStream.Seek(0, SeekOrigin.Begin);
            return Assembly.Load(memoryStream.ToArray());
        }
    }
    public interface IApiClient
    {
        Task<List<WeatherForecast>> GetWeatherForecastAsync(); // Replace with your actual method name and return type
    }
    public class WeatherForecast
    {
        public DateTime Date { get; set; }
        public int TemperatureC { get; set; }
        public int TemperatureF { get; set; }
        public string Summary { get; set; }
    }
}

Imports NSwag.CodeGeneration.CSharp
Imports NSwag
Imports System.Reflection
Imports System.CodeDom.Compiler
Imports Microsoft.CodeAnalysis
Friend Class Program
	Shared Async Function Main(ByVal args() As String) As Task
		Dim wclient As New System.Net.WebClient()
		' Create JSON file data from the Swagger net core web API
		Dim document = Await OpenApiDocument.FromJsonAsync(wclient.DownloadString("http://localhost:5013/swagger/v1/swagger.json"))
		wclient.Dispose()
		Dim settings = New CSharpClientGeneratorSettings With {
			.ClassName = "Weather",
			.CSharpGeneratorSettings = { [Namespace] = "Demo" }
		}
		Dim generator = New CSharpClientGenerator(document, settings)
		Dim code = generator.GenerateFile()
		Dim assembly = CompileCode(code)
		Dim clientType = assembly.GetType("Demo.WeatherClient") ' Replace with your actual client class name
		Dim httpClient As New HttpClient()
		Dim client = DirectCast(Activator.CreateInstance(clientType, httpClient), IApiClient)
		Dim result = Await client.GetWeatherForecastAsync()
		For Each item In result
			Console.WriteLine($"Date: {item.Date} F: {item.TemperatureF} C: {item.TemperatureC} Summary: {item.Summary}")
		Next item
	End Function
	Private Shared Function CompileCode(ByVal code As String) As System.Reflection.Assembly
		Using memoryStream As New MemoryStream()
			Dim assemblyPath = Path.GetDirectoryName(GetType(Object).Assembly.Location)
			Dim references As New List(Of MetadataReference)()
			references.Add(MetadataReference.CreateFromFile(GetType(Object).GetTypeInfo().Assembly.Location))
			references.Add(MetadataReference.CreateFromFile(Path.Combine(assemblyPath, "Microsoft.AspNetCore.Mvc.dll")))
			references.Add(MetadataReference.CreateFromFile(Path.Combine(assemblyPath, "System.Web.Http.dll")))
			Dim compilation = Microsoft.CodeAnalysis.CSharp.CSharpCompilation.Create("ApiClient").AddReferences(Microsoft.CodeAnalysis.MetadataReference.CreateFromFile(GetType(Object).Assembly.Location)).AddSyntaxTrees(Microsoft.CodeAnalysis.CSharp.SyntaxFactory.ParseSyntaxTree(code)).AddReferences(references)
			Dim emitResult = compilation.Emit(memoryStream)
			If Not emitResult.Success Then
				Dim diagnostics = emitResult.Diagnostics
				Console.WriteLine("Compilation errors:")
				For Each diagnostic In diagnostics
					Console.WriteLine(diagnostic)
				Next diagnostic
				Return Nothing
			End If
			memoryStream.Seek(0, SeekOrigin.Begin)
			Return System.Reflection.Assembly.Load(memoryStream.ToArray())
		End Using
	End Function
	Public Interface IApiClient
		Function GetWeatherForecastAsync() As Task(Of List(Of WeatherForecast)) ' Replace with your actual method name and return type
	End Interface
	Public Class WeatherForecast
		Public Property [Date]() As DateTime
		Public Property TemperatureC() As Integer
		Public Property TemperatureF() As Integer
		Public Property Summary() As String
	End Class
End Class

VB C#

使用したいAPIについては、Swagger仕様のURLを指定します。(swaggerUrl). 次に、DLLアセンブリに生成され実行されるクライアントコードが定義されます。 OpenApiDocumentが使用されます。指定されたURLからSwaggerドキュメントを非同期で読み込むには、FromJsonAsyncを使用します。生成されたクライアントコードを変更するには、コードジェネレーターの設定を調整します。(CSharpClientGeneratorSettings (C# クライアント生成設定)). この例では、生成されたクライアントコードのクラス名と名前空間が指定されています。

ロードされたSwaggerドキュメントから、CSharpClientGeneratorのインスタンスを構築し、それを使用してクライアントコードを生成します。(クライアントコード). 作成されたクライアントコードは指定された出力パスに保存されます。手順中に発生する可能性のある例外やエラーに対応し、関連する通知をコンソールに表示します。

NSwag C#（開発者のための仕組み）：図2 - 上記コードのコンソール出力

NSwag操作

クライアントコードの生成

NSwagは、Swagger仕様を使用してJava、TypeScript、C#など多くの言語でクライアントコードを生成することができます。これにより、開発者がアプリケーションでAPIを簡単に使用できるようになります。

サーバーコードの生成

Swagger仕様を基に、NSwagはASP.NET Coreコントローラーのようなサーバーコードを生成することもできます。これは、API実装のためのサーバーサイドコードを迅速に作成するのに役立ちます。

インタラクティブなAPIドキュメントの作成

Swagger仕様を考慮して、NSwagはSwagger UIのようなインタラクティブなAPIドキュメントを生成することができます。 APIエンドポイントの探索とテストのために、使いやすいインターフェイスがこのドキュメントによって提供されます。

プロキシクラスの生成

SOAPベースのAPIと統合するために、NSwagはプロキシクラスを生成できます。これにより、プログラマーは生成されたクライアントコードを使用して、アプリケーション内からSOAPサービスにアクセスすることができます。

Swagger仕様の検証

NSwagは、Swagger仕様がOpenAPI/Swagger標準に従っていることを確認することができます。これにより、APIドキュメントのエラーや不一致を確認しやすくなります。

IronPDFとNSwagの統合

開発者は、NSwagとIronPDFを統合することで、両方の技術の利点を活用し、APIドキュメントのワークフローを改善することができます。開発者は、NSwagを使用してSwagger仕様を生成することで、すぐに利用可能で共有可能な、完全でオフライン対応の.NET Web APIドキュメントを作成できます。IronPDFでPDFに変換します。. 以下の手順は統合プロセスの一部です：

IronPDF をインストール

Visual Studio プロジェクトを開始します。
「ツール」 > 「NuGet パッケージマネージャー」 > 「パッケージマネージャーコンソール」を選択します。
コマンドプロンプトを開き、パッケージマネージャーコンソールで次のコマンドを入力してください:

Install-Package IronPdf

または、ソリューションのためにNuGetパッケージマネージャを使用してIronPDFをインストールすることもできます。
検索結果からIronPDFパッケージを選択し、"インストール "オプションをクリックしてください。 Visual Studioは、ダウンロードおよびインストールを代わりに処理します。
NuGetは、IronPDFパッケージとプロジェクトに必要なすべての依存関係をインストールします。
インストール後、IronPDF をプロジェクトで利用できます。

NuGetウェブサイトからインストールする

IronPDFの機能、互換性、利用可能なダウンロードに関する追加情報については、以下をご覧ください。NuGetのIronPdfページ.

DLL を使用してインストール

また、DLLファイルを使ってIronPDFをプロジェクトに直接組み込むこともできます。DLLを含むZIPファイルをダウンロードするにはIronPdfダウンロードリンク. ファイルを解凍し、DLLをプロジェクトに追加してください。

DLLを含むZIPファイルを入手するには、解凍後、DLLをプロジェクトに組み込んでください。

ロジックの実装

NSwagを活用することで、開発者はIronPDFと組み合わせてCodeGeneration.CSharpを使用することにより、APIドキュメントとクライアントコードをより迅速に作成することができます。以下の手順は、統合ワークフローに含まれます：

クライアントコードの生成: Swagger仕様からC#クライアントコードを生成するには、NSwag.CodeGeneration.CSharpを使用します。このステップでは、APIエンドポイントと通信するためのクライアントクラスとメソッドの作成が自動化されます。
**Swagger仕様からJSONドキュメントを作成するには、CodeGeneration.CSharpを使用します。この段階では、リクエスト/レスポンス形式、認証技術、およびAPIクライアントエンドポイントが、人間が読みやすいドキュメントに作成されます。
JSONをPDFに変換： 生成されたコードの結果をPDFドキュメントに変換するには、IronPDFを使用します。この段階では、HTMLテキストが仕上げられたPDFドキュメントに変換され、共有や配布の準備が整います。
PDFドキュメントの改善: IronPDFを使用して、ヘッダー、フッター、ウォーターマーク、または独自のブランディングなど、PDFドキュメントにさらにコンテンツを追加します。このステージでは、開発者がPDFドキュメントの外観やブランディングを自分の好みに合わせてパーソナライズする能力が与えられます。

using IronPdf;
StringBuilder sb = new StringBuilder();

foreach (var item in result)
{
    sb.Append($"<p>Date: {item.Date} F: {item.TemperatureF} C: {item.TemperatureC} Summary: {item.Summary}</p>");
}
var Renderer = new IronPdf.HtmlToPdf();
var PDF = Renderer.RenderHtmlAsPdf(sb.ToString());
// Save PDF to file
PDF.SaveAs("output.pdf");
Console.WriteLine("PDF generated successfully!");
Console.ReadKey();

using IronPdf;
StringBuilder sb = new StringBuilder();

foreach (var item in result)
{
    sb.Append($"<p>Date: {item.Date} F: {item.TemperatureF} C: {item.TemperatureC} Summary: {item.Summary}</p>");
}
var Renderer = new IronPdf.HtmlToPdf();
var PDF = Renderer.RenderHtmlAsPdf(sb.ToString());
// Save PDF to file
PDF.SaveAs("output.pdf");
Console.WriteLine("PDF generated successfully!");
Console.ReadKey();

Imports IronPdf
Private sb As New StringBuilder()

For Each item In result
	sb.Append($"<p>Date: {item.Date} F: {item.TemperatureF} C: {item.TemperatureC} Summary: {item.Summary}</p>")
Next item
Dim Renderer = New IronPdf.HtmlToPdf()
Dim PDF = Renderer.RenderHtmlAsPdf(sb.ToString())
' Save PDF to file
PDF.SaveAs("output.pdf")
Console.WriteLine("PDF generated successfully!")
Console.ReadKey()

VB C#

上記のコードは、結果オブジェクトから取得したデータにアクセスし、「Date」、「TemperatureF」、「TemperatureC」、「Summary」のフィールドをループ内で段落に追加します。次に、PDFの出力ファイルパスを指定し、PDFが正常に生成されたことをユーザーに通知します。

以下は上記のコードからの結果です。

NSwag C#（開発者のための仕組み）：図4 - 上記のコードからの出力例

結論

CodeGeneration NSwagテクノロジーのCSharpやIronPDFは、クライアントコードの生成およびAPIドキュメンテーションのプロセスを効率化するためにうまく連携します。これらのツールをC#アプリケーションに統合することで、開発者はAPI駆動のソリューションの作成をスピードアップし、APIドキュメントの作成を自動化し、プロフェッショナルな外観のPDF出版物を生成できます。 NSwag.CodeGeneration.CSharp と IronPDF は、デスクトップ、ウェブ、クラウドベースのアプリケーションを開発しているかどうかにかかわらず、API を効率的にドキュメント化し、C# でクライアントコードを生成するための完全なソリューションを提供します。

$749 Liteバンドルには、永久ライセンス、1年間のソフトウェア保守、およびライブラリのアップグレードが含まれています。 IronPDFは再配布と時間に制限のある無料ライセンスを提供しています。ユーザーは試用期間中、透かしを視認することなくソリューションを評価できます。価格とライセンスの詳細については、以下を参照してください。IronPDFのライセンス情報. に移動しますIron ソフトウェアライブラリのページIron Softwareの製品ライブラリの詳細については、こちらをご覧ください。

< 以前
Dapper C#（開発者向けの動作方法）

次へ >
Fluent C#（開発者向けの仕組み）