C# WebAPI入門｜ASP.NET CoreでCRUD・Swagger・DB連携まで初心者にもわかる作り方

はじめに

C# WebAPIは、Webアプリ、スマホアプリ、外部システムなどからHTTP経由でデータを取得・登録・更新・削除するための仕組みです。C#でWebAPIを作る場合、現在はASP.NET Core Web APIを使うのが一般的です。

この記事では、初心者向けに「C# WebAPIとは何か」から、ASP.NET Coreプロジェクトの作成、Swaggerでの動作確認、CRUD APIの実装、Entity Framework CoreによるDB連携までを一通り解説します。

最終的には、次のようなAPIを作れる状態を目指します。

http
GET    /api/items
GET    /api/items/{id}
POST   /api/items
PUT    /api/items/{id}
DELETE /api/items/{id}

C# WebAPIの基本を押さえれば、社内システム、管理画面、SPA、スマホアプリ、外部連携APIなど、さまざまな開発に応用できます。

1. C# WebAPIとは？初心者がまず知るべき基本

1-1. WebAPIの役割とできること

WebAPIとは、HTTP通信を使ってアプリケーション同士がデータをやり取りするための窓口です。

たとえば、フロントエンドのReactやVue.jsからC# WebAPIにリクエストを送り、商品一覧やユーザー情報をJSON形式で受け取る、といった使い方をします。

WebAPIでは主に次のような処理を行います。

http
GET    データを取得する
POST   データを登録する
PUT    データを更新する
DELETE データを削除する

この4つの操作はCRUDと呼ばれ、WebAPI開発の基本になります。

1-2. C#でWebAPIを作るならASP.NET Coreが選ばれる理由

C#でWebAPIを作る場合、ASP.NET Coreがよく使われます。

ASP.NET CoreはMicrosoftが提供するWebアプリケーション開発フレームワークで、WindowsだけでなくLinuxやmacOSでも動作します。高速で、クラウド環境にも対応しやすく、企業向けシステムでも多く採用されています。

ASP.NET Coreが選ばれる主な理由は次のとおりです。

・C#で型安全に開発できる
・Visual Studioとの相性がよい
・SwaggerやOpenAPIに対応しやすい
・Entity Framework CoreでDB連携しやすい
・認証、DI、ログ、設定管理などが標準で整っている

初心者がC# WebAPIを学ぶなら、まずASP.NET Core Web APIから始めるのがおすすめです。

1-3. ASP.NET Core Web APIとMVC・Minimal APIの違い

ASP.NET Coreには、APIを作る方法が複数あります。

代表的なのは次の3つです。

ASP.NET Core Web API：コントローラーを使ってAPIを作る方式
ASP.NET Core MVC：画面とサーバー処理をまとめて作る方式
Minimal API：少ないコードで軽量なAPIを作る方式

ASP.NET Core Web APIは、Controllerクラスを作成し、GETやPOSTなどの処理をメソッドとして定義します。構成がわかりやすく、実務でも採用されやすい方法です。

MVCは、画面表示用のViewを含むWebアプリケーション向けです。一方、Minimal APIは小規模なAPIやマイクロサービスに向いています。

初心者がCRUD、DB連携、Swagger、設計の基本を学ぶなら、まずはコントローラー方式のASP.NET Core Web APIをおすすめします。

1-4. この記事で作るサンプルAPIの完成イメージ

この記事では、Itemというシンプルなデータを扱うAPIを作ります。

Itemのイメージは次のとおりです。

JSON
{
  "id": 1,
  "name": "ノートパソコン",
  "price": 120000,
  "isAvailable": true
}

作成するAPIは次の5つです。

http
GET    /api/items        商品一覧を取得
GET    /api/items/1      商品詳細を取得
POST   /api/items        商品を登録
PUT    /api/items/1      商品を更新
DELETE /api/items/1      商品を削除

最初はメモリ上のデータで動作を確認し、その後Entity Framework Coreを使ってDB保存に対応させます。

2. C# WebAPI開発に必要な環境を準備する

2-1. 必要なツール一覧：Visual Studio・.NET SDK・SQL Server/SQLite

C# WebAPI開発には、次のツールを用意します。

・Visual Studio 2022以降
・.NET SDK
・SQL Server または SQLite
・ブラウザ
・必要に応じて Postman や curl

初心者にはVisual Studioを使った開発がおすすめです。プロジェクト作成、実行、デバッグ、NuGetパッケージ管理などを画面操作で行えるため、学習しやすいです。

軽量に始めたい場合は、Visual Studio Codeと.NET CLIでも開発できます。

2-2. .NETのバージョンはどれを選べばよいか

これからC# WebAPIを学ぶなら、基本的にはサポート中のLTS版を選ぶのがおすすめです。

2026年時点では、.NET 10がLTS版として利用できます。.NET 8もLTS版ですが、これから新規に学習・開発するなら、特別な理由がなければ.NET 10を選ぶとよいでしょう。

企業案件や既存システムでは、プロジェクトの方針に合わせて.NET 8、.NET 9、.NET 10などを使い分けます。

2-3. ASP.NET Core Web APIプロジェクトを新規作成する手順

Visual Studioで作成する場合は、次の手順です。

1. Visual Studioを起動する
2. 「新しいプロジェクトの作成」を選択する
3. 「ASP.NET Core Web API」を選択する
4. プロジェクト名を入力する
5. フレームワークに.NET 10などを選択する
6. OpenAPIまたはSwaggerを有効にする
7. 作成をクリックする

.NET CLIを使う場合は、次のコマンドで作成できます。

Bash
dotnet new webapi -n SampleWebApi
cd SampleWebApi
dotnet run

実行後、ブラウザでSwagger UIが表示されれば、C# WebAPIプロジェクトの作成は成功です。

2-4. プロジェクト構成と主要ファイルの役割

ASP.NET Core Web APIプロジェクトには、主に次のようなファイルがあります。

Program.cs
アプリケーションの起動設定、DI登録、ミドルウェア設定を書くファイル

appsettings.json
接続文字列やログ設定などを管理する設定ファイル

Controllersフォルダ
APIのエンドポイントを定義するコントローラーを配置する場所

Modelsフォルダ
エンティティやDTOなどのクラスを配置する場所

Properties/launchSettings.json
開発時の起動URLや環境変数を管理するファイル

初心者が最初に理解すべきなのは、Program.csとControllersフォルダです。

Program.csでアプリ全体の設定を行い、Controllerで実際のAPI処理を書きます。

3. SwaggerでAPIの動作確認ができる状態にする

3-1. Swaggerとは？初心者が使うメリット

Swaggerは、WebAPIの仕様を確認したり、ブラウザ上からAPIを実行したりできる便利なツールです。

C# WebAPI開発では、Swagger UIを使うことでPostmanなどを使わなくても、GET、POST、PUT、DELETEの動作確認ができます。

Swaggerを使うメリットは次のとおりです。

・API一覧をブラウザで確認できる
・リクエストパラメータを入力して実行できる
・レスポンス内容を確認できる
・フロントエンド担当者との共有がしやすい
・OpenAPI仕様としてAPI定義を管理できる

初心者にとっては、APIの動きを視覚的に確認できる点が大きなメリットです。

3-2. ASP.NET Core Web APIでSwaggerを有効化する

プロジェクト作成時にOpenAPIやSwaggerを有効にしていれば、基本的な設定は自動で入っています。

Program.csには、次のような設定があります。

C#
var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

ポイントは次の3つです。

C#
builder.Services.AddSwaggerGen();
app.UseSwagger();
app.UseSwaggerUI();

これらが設定されていると、開発環境でSwagger UIを表示できます。

3-3. Swagger UIでGETリクエストを実行してみる

プロジェクトを実行すると、次のようなURLでSwagger UIが表示されます。

https://localhost:xxxx/swagger

Swagger UIでは、表示されたエンドポイントを開き、「Try it out」をクリックしてから「Execute」を押すとAPIを実行できます。

たとえば、GET APIを実行すると、レスポンスとしてJSONが表示されます。

JSON
[
  {
    "id": 1,
    "name": "Sample Item",
    "price": 1000,
    "isAvailable": true
  }
]

このように、Swaggerを使うとAPIの動作確認が非常に簡単になります。

3-4. Swaggerが表示されないときの確認ポイント

Swaggerが表示されない場合は、次の点を確認しましょう。

・URLが /swagger になっているか
・Program.csにUseSwaggerとUseSwaggerUIがあるか
・開発環境で実行しているか
・ブラウザに表示されているポート番号が正しいか
・HTTPS証明書の警告で止まっていないか

特に、次のようにDevelopment環境のときだけSwaggerを有効にしているケースが多いです。

C#
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

本番環境ではSwaggerを無効にする構成も一般的なので、環境設定も確認しましょう。

4. CRUD APIを作る前にモデルとデータ設計を行う

4-1. CRUDとは？Create・Read・Update・Deleteの意味

CRUDとは、データ操作の基本である次の4つを表します。

Create：作成
Read：取得
Update：更新
Delete：削除

WebAPIでは、HTTPメソッドと対応させて次のように設計します。

Create → POST
Read   → GET
Update → PUT または PATCH
Delete → DELETE

C# WebAPIを学ぶうえで、CRUD APIの実装は最初に習得すべき重要なステップです。

4-2. サンプルで使うエンティティを作成する

まず、APIで扱うItemエンティティを作成します。

Modelsフォルダを作成し、Item.csを追加します。

C#
namespace SampleWebApi.Models;

public class Item
{
    public int Id { get; set; }

    public string Name { get; set; } = string.Empty;

    public decimal Price { get; set; }

    public bool IsAvailable { get; set; }
}

このItemクラスが、APIで扱う基本データになります。

各プロパティの意味は次のとおりです。

Id：一意の識別子
Name：商品名
Price：価格
IsAvailable：販売可能かどうか

4-3. DTOを使うべき場面と初心者向けの考え方

DTOとは、Data Transfer Objectの略で、APIのリクエストやレスポンスで使うデータ受け渡し用のクラスです。

初心者のうちは、エンティティをそのままリクエストやレスポンスに使っても学習はできます。ただし、実務ではDTOを使うことが多いです。

理由は次のとおりです。

・DBの構造をそのまま外部に見せないため
・登録時と更新時で必要な項目を分けるため
・レスポンスに不要な情報を含めないため
・入力チェックをしやすくするため

たとえば、登録用DTOは次のように作れます。

C#
using System.ComponentModel.DataAnnotations;

namespace SampleWebApi.Models;

public class CreateItemRequest
{
    [Required]
    [MaxLength(100)]
    public string Name { get; set; } = string.Empty;

    [Range(0, 9999999)]
    public decimal Price { get; set; }

    public bool IsAvailable { get; set; }
}

更新用DTOも作っておくと、後から拡張しやすくなります。

C#
using System.ComponentModel.DataAnnotations;

namespace SampleWebApi.Models;

public class UpdateItemRequest
{
    [Required]
    [MaxLength(100)]
    public string Name { get; set; } = string.Empty;

    [Range(0, 9999999)]
    public decimal Price { get; set; }

    public bool IsAvailable { get; set; }
}

4-4. バリデーション項目を設計する

WebAPIでは、不正な入力を受け付けないようにバリデーションを設計します。

今回のItemでは、次のようなルールを設定します。

Name：必須、最大100文字
Price：0以上
IsAvailable：trueまたはfalse

C#ではDataAnnotationsを使うと、簡単に入力チェックを設定できます。

C#
[Required]
[MaxLength(100)]
public string Name { get; set; } = string.Empty;

[Range(0, 9999999)]
public decimal Price { get; set; }

ControllerにApiController属性を付けると、モデル検証エラー時に自動で400 Bad Requestを返してくれます。

5. コントローラーを作成してCRUD処理を実装する

5-1. ControllerBaseとApiController属性の役割

ASP.NET Core Web APIでは、ControllerBaseを継承してAPI用のコントローラーを作成します。

C#
using Microsoft.AspNetCore.Mvc;
using SampleWebApi.Models;

namespace SampleWebApi.Controllers;

[ApiController]
[Route("api/[controller]")]
public class ItemsController : ControllerBase
{
}

それぞれの役割は次のとおりです。

ControllerBase：API用の基本機能を提供するクラス
ApiController：入力検証やバインディングを便利にする属性
Route：URLのルーティングを指定する属性

[Route("api/[controller]")]の場合、ItemsControllerは/api/itemsとしてアクセスできます。

5-2. 一覧取得API：GET /api/items

まずはメモリ上のリストを使って、一覧取得APIを作成します。

C#
using Microsoft.AspNetCore.Mvc;
using SampleWebApi.Models;

namespace SampleWebApi.Controllers;

[ApiController]
[Route("api/[controller]")]
public class ItemsController : ControllerBase
{
    private static readonly List<Item> Items = new()
    {
        new Item { Id = 1, Name = "ノートパソコン", Price = 120000, IsAvailable = true },
        new Item { Id = 2, Name = "マウス", Price = 3000, IsAvailable = true }
    };

    [HttpGet]
    public ActionResult<IEnumerable<Item>> GetItems()
    {
        return Ok(Items);
    }
}

[HttpGet]を付けることで、GETリクエストに対応するメソッドになります。

レスポンスは次のようなJSONになります。

JSON
[
  {
    "id": 1,
    "name": "ノートパソコン",
    "price": 120000,
    "isAvailable": true
  },
  {
    "id": 2,
    "name": "マウス",
    "price": 3000,
    "isAvailable": true
  }
]

5-3. 詳細取得API：GET /api/items/{id}

次に、IDを指定して1件取得するAPIを作ります。

C#
[HttpGet("{id}")]
public ActionResult<Item> GetItem(int id)
{
    var item = Items.FirstOrDefault(x => x.Id == id);

    if (item == null)
    {
        return NotFound();
    }

    return Ok(item);
}

[HttpGet("{id}")]と書くことで、/api/items/1のようなURLに対応できます。

対象データが見つからない場合は、404 Not Foundを返します。

5-4. 新規登録API：POST /api/items

新規登録APIでは、リクエストボディからデータを受け取り、リストに追加します。

C#
[HttpPost]
public ActionResult<Item> CreateItem(CreateItemRequest request)
{
    var newId = Items.Any() ? Items.Max(x => x.Id) + 1 : 1;

    var item = new Item
    {
        Id = newId,
        Name = request.Name,
        Price = request.Price,
        IsAvailable = request.IsAvailable
    };

    Items.Add(item);

    return CreatedAtAction(nameof(GetItem), new { id = item.Id }, item);
}

POSTリクエストの例は次のとおりです。

JSON
{
  "name": "キーボード",
  "price": 8000,
  "isAvailable": true
}

登録に成功した場合は、201 Createdを返します。

5-5. 更新API：PUT /api/items/{id}

更新APIでは、IDに一致するデータを探し、内容を書き換えます。

C#
[HttpPut("{id}")]
public IActionResult UpdateItem(int id, UpdateItemRequest request)
{
    var item = Items.FirstOrDefault(x => x.Id == id);

    if (item == null)
    {
        return NotFound();
    }

    item.Name = request.Name;
    item.Price = request.Price;
    item.IsAvailable = request.IsAvailable;

    return NoContent();
}

PUTリクエストの例は次のとおりです。

JSON
{
  "name": "ゲーミングキーボード",
  "price": 15000,
  "isAvailable": true
}

更新に成功した場合、204 No Contentを返すのが一般的です。

5-6. 削除API：DELETE /api/items/{id}

削除APIでは、IDに一致するデータを削除します。

C#
[HttpDelete("{id}")]
public IActionResult DeleteItem(int id)
{
    var item = Items.FirstOrDefault(x => x.Id == id);

    if (item == null)
    {
        return NotFound();
    }

    Items.Remove(item);

    return NoContent();
}

削除対象が存在しない場合は404 Not Found、削除に成功した場合は204 No Contentを返します。

5-7. HTTPステータスコードの正しい返し方

WebAPIでは、処理結果に応じて適切なHTTPステータスコードを返すことが重要です。

よく使うステータスコードは次のとおりです。

200 OK：取得や更新結果の返却に成功
201 Created：新規作成に成功
204 No Content：成功したが返す本文がない
400 Bad Request：リクエスト内容が不正
401 Unauthorized：認証が必要
403 Forbidden：権限がない
404 Not Found：対象データが存在しない
500 Internal Server Error：サーバー内部エラー

C# WebAPIでは、次のようなメソッドで簡単に返せます。

C#
return Ok(data);
return CreatedAtAction(nameof(GetItem), new { id = item.Id }, item);
return NoContent();
return BadRequest();
return NotFound();

HTTPステータスコードを正しく使うことで、フロントエンドや外部システムがAPIの結果を判断しやすくなります。

6. Entity Framework CoreでDB連携を実装する

6-1. Entity Framework Coreとは？SQLを書かずにDB操作できる仕組み

Entity Framework Coreは、C#のクラスを使ってデータベース操作を行えるORMです。

ORMとは、Object Relational Mapperの略で、C#のオブジェクトとデータベースのテーブルを対応させる仕組みです。

通常、DB操作にはSQLが必要です。

SQL
SELECT * FROM Items;

Entity Framework Coreを使うと、C#で次のように書けます。

C#
var items = await _context.Items.ToListAsync();

SQLを直接書かなくてもCRUD処理を実装できるため、C# WebAPIではよく使われます。

6-2. 必要なNuGetパッケージを追加する

SQLiteを使う場合は、次のパッケージを追加します。

Bash
dotnet add package Microsoft.EntityFrameworkCore.Sqlite
dotnet add package Microsoft.EntityFrameworkCore.Design

SQL Serverを使う場合は、次のパッケージを追加します。

Bash
dotnet add package Microsoft.EntityFrameworkCore.SqlServer
dotnet add package Microsoft.EntityFrameworkCore.Design

初心者の学習用途では、環境構築が簡単なSQLiteがおすすめです。

6-3. DbContextを作成する

DbContextは、C# WebAPIとDBの橋渡しをするクラスです。

Dataフォルダを作成し、AppDbContext.csを追加します。

C#
using Microsoft.EntityFrameworkCore;
using SampleWebApi.Models;

namespace SampleWebApi.Data;

public class AppDbContext : DbContext
{
    public AppDbContext(DbContextOptions<AppDbContext> options)
        : base(options)
    {
    }

    public DbSet<Item> Items => Set<Item>();
}

DbSet<Item>は、Itemsテーブルに対応します。

6-4. 接続文字列をappsettings.jsonに設定する

SQLiteを使う場合、appsettings.jsonに接続文字列を追加します。

JSON
{
  "ConnectionStrings": {
    "DefaultConnection": "Data Source=sample.db"
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*"
}

SQL Serverを使う場合は、次のような接続文字列になります。

JSON
{
  "ConnectionStrings": {
    "DefaultConnection": "Server=localhost;Database=SampleWebApiDb;Trusted_Connection=True;TrustServerCertificate=True"
  }
}

学習段階ではSQLite、本格開発ではSQL ServerやPostgreSQLを選ぶとよいでしょう。

6-5. Program.csでDbContextをDI登録する

Program.csにDbContextを登録します。

SQLiteの場合は次のように書きます。

C#
using Microsoft.EntityFrameworkCore;
using SampleWebApi.Data;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

builder.Services.AddDbContext<AppDbContext>(options =>
    options.UseSqlite(builder.Configuration.GetConnectionString("DefaultConnection")));

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

AddDbContextでDI登録することで、ControllerのコンストラクタからAppDbContextを受け取れるようになります。

6-6. マイグレーションでテーブルを作成する

Entity Framework Coreでは、マイグレーションを使ってテーブルを作成します。

次のコマンドを実行します。

Bash
dotnet ef migrations add InitialCreate
dotnet ef database update

dotnet efコマンドが使えない場合は、ツールをインストールします。

Bash
dotnet tool install --global dotnet-ef

成功すると、SQLiteの場合はsample.dbというDBファイルが作成されます。

6-7. CRUD処理をDB保存に対応させる

ControllerをDB対応に書き換えます。

C#
using Microsoft.AspNetCore.Mvc;
using Microsoft.EntityFrameworkCore;
using SampleWebApi.Data;
using SampleWebApi.Models;

namespace SampleWebApi.Controllers;

[ApiController]
[Route("api/[controller]")]
public class ItemsController : ControllerBase
{
    private readonly AppDbContext _context;

    public ItemsController(AppDbContext context)
    {
        _context = context;
    }

    [HttpGet]
    public async Task<ActionResult<IEnumerable<Item>>> GetItems()
    {
        var items = await _context.Items.ToListAsync();
        return Ok(items);
    }

    [HttpGet("{id}")]
    public async Task<ActionResult<Item>> GetItem(int id)
    {
        var item = await _context.Items.FindAsync(id);

        if (item == null)
        {
            return NotFound();
        }

        return Ok(item);
    }

    [HttpPost]
    public async Task<ActionResult<Item>> CreateItem(CreateItemRequest request)
    {
        var item = new Item
        {
            Name = request.Name,
            Price = request.Price,
            IsAvailable = request.IsAvailable
        };

        _context.Items.Add(item);
        await _context.SaveChangesAsync();

        return CreatedAtAction(nameof(GetItem), new { id = item.Id }, item);
    }

    [HttpPut("{id}")]
    public async Task<IActionResult> UpdateItem(int id, UpdateItemRequest request)
    {
        var item = await _context.Items.FindAsync(id);

        if (item == null)
        {
            return NotFound();
        }

        item.Name = request.Name;
        item.Price = request.Price;
        item.IsAvailable = request.IsAvailable;

        await _context.SaveChangesAsync();

        return NoContent();
    }

    [HttpDelete("{id}")]
    public async Task<IActionResult> DeleteItem(int id)
    {
        var item = await _context.Items.FindAsync(id);

        if (item == null)
        {
            return NotFound();
        }

        _context.Items.Remove(item);
        await _context.SaveChangesAsync();

        return NoContent();
    }
}

これで、C# WebAPIのCRUD処理がDB保存に対応しました。

7. SwaggerでCRUD APIをテストする

7-1. GETでデータ一覧を取得する

Swagger UIを開き、GET /api/itemsを実行します。

まだデータが登録されていない場合は、空の配列が返ります。

JSON
[]

データが登録されている場合は、次のようなレスポンスになります。

JSON
[
  {
    "id": 1,
    "name": "ノートパソコン",
    "price": 120000,
    "isAvailable": true
  }
]

7-2. POSTでデータを登録する

POST /api/itemsを開き、リクエストボディに次のJSONを入力します。

JSON
{
  "name": "ノートパソコン",
  "price": 120000,
  "isAvailable": true
}

実行して201 Createdが返れば登録成功です。

登録後にGET /api/itemsを実行すると、追加したデータを確認できます。

7-3. PUTでデータを更新する

PUT /api/items/{id}を開き、idに更新対象のIDを入力します。

リクエストボディには、更新後の内容を入力します。

JSON
{
  "name": "高性能ノートパソコン",
  "price": 150000,
  "isAvailable": true
}

実行して204 No Contentが返れば更新成功です。

7-4. DELETEでデータを削除する

DELETE /api/items/{id}を開き、削除したいIDを入力します。

実行して204 No Contentが返れば削除成功です。

削除後にGET /api/items/{id}を実行すると、404 Not Foundになります。

7-5. リクエストボディとレスポンスの見方

Swaggerでは、API実行時に次の情報を確認できます。

Request URL：実行されたAPIのURL
Request body：送信したJSON
Response body：返ってきたJSON
Response code：HTTPステータスコード
Response headers：レスポンスヘッダー

初心者は特に、Response codeとResponse bodyを確認しましょう。

成功しているのか、入力エラーなのか、データが見つからないのかを判断できます。

7-6. よくあるエラーと原因の切り分け方

C# WebAPI開発でよくあるエラーは次のとおりです。

400 Bad Request：JSONの形式ミス、必須項目不足、バリデーションエラー
404 Not Found：URL間違い、IDに対応するデータがない
500 Internal Server Error：例外発生、DB接続エラー、マイグレーション未実行
Swaggerが表示されない：設定不足、URL間違い、Development環境でない

DB関連でエラーが出る場合は、次を確認します。

・接続文字列が正しいか
・DbContextがDI登録されているか
・マイグレーションを実行したか
・テーブルが作成されているか
・SaveChangesAsyncを呼んでいるか

エラーが出たら、まずステータスコード、レスポンス本文、Visual Studioの出力ログを確認しましょう。

8. 初心者がつまずきやすいC# WebAPIの重要ポイント

8-1. 依存性注入（DI）の基本

DIとは、必要なクラスを外部から渡して使う仕組みです。

ASP.NET CoreではDIが標準で組み込まれています。

たとえば、DbContextはProgram.csで登録します。

C#
builder.Services.AddDbContext<AppDbContext>(options =>
    options.UseSqlite(builder.Configuration.GetConnectionString("DefaultConnection")));

Controllerでは、コンストラクタで受け取ります。

C#
private readonly AppDbContext _context;

public ItemsController(AppDbContext context)
{
    _context = context;
}

このようにすることで、Controllerが自分でDbContextを作成する必要がなくなります。

DIを使うと、テストしやすくなり、クラス同士の結合も弱くできます。

8-2. 非同期処理 async/await の使い方

DBアクセスや外部API通信は時間がかかる処理です。

ASP.NET Core Web APIでは、非同期処理としてasyncとawaitを使うのが一般的です。

C#
[HttpGet]
public async Task<ActionResult<IEnumerable<Item>>> GetItems()
{
    var items = await _context.Items.ToListAsync();
    return Ok(items);
}

ポイントは次のとおりです。

・メソッドにasyncを付ける
・戻り値をTask<T>にする
・非同期メソッドをawaitで呼び出す
・EF CoreではToListAsync、FindAsync、SaveChangesAsyncなどを使う

非同期処理を使うことで、サーバーのリソースを効率よく使えます。

8-3. 例外処理とエラーレスポンスの設計

実務のWebAPIでは、例外が発生したときのレスポンス設計も重要です。

初心者のうちは、まず次の考え方を押さえましょう。

入力ミス：400 Bad Request
認証エラー：401 Unauthorized
権限不足：403 Forbidden
データなし：404 Not Found
競合：409 Conflict
サーバー内部エラー：500 Internal Server Error

Controller内で想定できるエラーは、明示的に返します。

C#
if (item == null)
{
    return NotFound();
}

想定外の例外は、ミドルウェアで共通処理にするのが実務的です。

8-4. CORS設定が必要になるケース

CORSとは、異なるオリジンからAPIにアクセスする際の制限です。

たとえば、フロントエンドがhttp://localhost:3000、C# WebAPIがhttps://localhost:7001で動いている場合、CORS設定が必要になることがあります。

Program.csに次のように設定します。

C#
builder.Services.AddCors(options =>
{
    options.AddPolicy("AllowFrontend", policy =>
    {
        policy.WithOrigins("http://localhost:3000")
              .AllowAnyHeader()
              .AllowAnyMethod();
    });
});

そして、ミドルウェアを追加します。

C#
app.UseCors("AllowFrontend");

本番環境では、AllowAnyOriginを安易に使わず、許可するドメインを明確に指定しましょう。

8-5. appsettings.jsonと環境別設定の使い分け

ASP.NET Coreでは、設定情報をappsettings.jsonで管理します。

JSON
{
  "ConnectionStrings": {
    "DefaultConnection": "Data Source=sample.db"
  }
}

開発環境用には、appsettings.Development.jsonを使えます。

JSON
{
  "ConnectionStrings": {
    "DefaultConnection": "Data Source=sample-dev.db"
  }
}

実務では、開発環境、ステージング環境、本番環境で接続先DBやログレベルが異なります。

そのため、環境ごとに設定ファイルや環境変数を使い分けることが重要です。

8-6. ログ出力で原因を調査する方法

エラー調査にはログが欠かせません。

Controllerでログを使う場合は、ILoggerをDIで受け取ります。

C#
private readonly ILogger<ItemsController> _logger;

public ItemsController(AppDbContext context, ILogger<ItemsController> logger)
{
    _context = context;
    _logger = logger;
}

ログを出力する例です。

C#
_logger.LogInformation("商品一覧を取得しました。");
_logger.LogWarning("商品が見つかりません。ID: {Id}", id);
_logger.LogError(ex, "商品登録中にエラーが発生しました。");

ログを適切に出すことで、障害発生時の原因調査がしやすくなります。

9. 実務を意識したWebAPI設計のベストプラクティス

9-1. RESTfulなURL設計の基本

WebAPIでは、URLはリソースを表すように設計します。

良い例は次のとおりです。

http
GET /api/items
GET /api/items/1
POST /api/items
PUT /api/items/1
DELETE /api/items/1

避けたい例は次のようなURLです。

http
GET /api/getItems
POST /api/createItem
POST /api/deleteItem

操作名をURLに含めるのではなく、HTTPメソッドで操作を表すのがRESTfulな設計です。

9-2. リクエストとレスポンスの命名ルール

C#ではプロパティ名にPascalCaseを使います。

C#
public string ItemName { get; set; } = string.Empty;

一方、JSONではcamelCaseがよく使われます。

JSON
{
  "itemName": "ノートパソコン"
}

ASP.NET Coreでは、標準でJSONがcamelCaseになる設定が使われることが多いです。

命名ルールはプロジェクト全体で統一しましょう。

9-3. Controller・Service・Repositoryに分ける考え方

小規模なサンプルではControllerに直接DB処理を書いても問題ありません。

しかし実務では、役割ごとにクラスを分けることが多いです。

Controller：HTTPリクエストとレスポンスを担当
Service：業務ロジックを担当
Repository：DBアクセスを担当

たとえば、ControllerはServiceを呼び出すだけにします。

C#
[HttpGet]
public async Task<IActionResult> GetItems()
{
    var items = await _itemService.GetItemsAsync();
    return Ok(items);
}

このように分けることで、コードの見通しがよくなり、テストもしやすくなります。

9-4. 入力チェックとセキュリティ対策

WebAPIでは、外部から送られてくるデータを信用してはいけません。

最低限、次の対策を行いましょう。

・必須項目のチェック
・文字数制限
・数値範囲のチェック
・不正なIDのチェック
・認証、認可の導入
・HTTPSの利用
・CORSの適切な設定
・機密情報をレスポンスに含めない

DataAnnotationsを使った入力チェックは、初心者でも導入しやすい方法です。

C#
[Required]
[MaxLength(100)]
public string Name { get; set; } = string.Empty;

セキュリティ対策は後回しにせず、設計段階から考えることが重要です。

9-5. 認証・認可を追加する場合の選択肢

WebAPIを公開する場合、認証と認可が必要になることがあります。

代表的な選択肢は次のとおりです。

JWT認証：SPAやスマホアプリとの連携でよく使う
Cookie認証：サーバーサイドWebアプリで使いやすい
OAuth 2.0 / OpenID Connect：外部IDプロバイダー連携で使う
Microsoft Entra ID：企業向け認証で使う

APIでは、JWT Bearer認証がよく使われます。

認証は「誰か」を確認する仕組みで、認可は「何をしてよいか」を制御する仕組みです。

9-6. フロントエンドや外部システムとの連携イメージ

C# WebAPIは、フロントエンドや外部システムと連携して使われます。

たとえば、ReactからAPIを呼び出す場合は次のようなイメージです。

JavaScript
const response = await fetch("https://localhost:7001/api/items");
const items = await response.json();
console.log(items);

外部システムからは、HTTPリクエストでJSONを送受信します。

http
POST /api/items
Content-Type: application/json

JSON
{
  "name": "外部連携商品",
  "price": 5000,
  "isAvailable": true
}

WebAPIは、システム同士をつなぐ入口として重要な役割を持ちます。

10. C# WebAPI開発でよくある質問

10-1. ASP.NET Core Web APIとASP.NET Web APIの違いは？

ASP.NET Web APIは、主に.NET Framework時代に使われていたWebAPI開発技術です。

一方、ASP.NET Core Web APIは、.NET Core以降のモダンなフレームワークで、クロスプラットフォーム対応、高速化、DI標準搭載などの特徴があります。

これから新規にC# WebAPIを学ぶなら、ASP.NET Core Web APIを選びましょう。

10-2. Minimal APIとコントローラーはどちらを選ぶべき？

小規模なAPIやシンプルなマイクロサービスなら、Minimal APIは便利です。

一方、初心者がCRUD、DTO、バリデーション、Controller設計、Service分離などを学ぶなら、コントローラー方式がおすすめです。

実務でも、規模が大きくなるAPIではコントローラー方式のほうが整理しやすいケースがあります。

10-3. DBはSQL Server・SQLite・PostgreSQLのどれがよい？

学習用途ならSQLiteが簡単です。ファイルベースで動作するため、DBサーバーを用意しなくても始められます。

Windows環境や企業システムではSQL Serverがよく使われます。

Linux環境やクラウドネイティブな構成ではPostgreSQLも人気があります。

選び方の目安は次のとおりです。

学習用：SQLite
Windows系業務システム：SQL Server
クラウド・OSS系システム：PostgreSQL

10-4. Swaggerは本番環境でも有効にしてよい？

SwaggerはAPI仕様の確認に便利ですが、本番環境で無制限に公開するのは注意が必要です。

本番環境で有効にする場合は、次の対策を検討しましょう。

・認証をかける
・社内ネットワークからのみアクセス可能にする
・公開してよいAPIだけ表示する
・不要であれば本番では無効化する

学習環境や開発環境では有効にして問題ありませんが、本番環境ではセキュリティを考慮しましょう。

10-5. WebAPIを公開・デプロイするには何が必要？

C# WebAPIを公開するには、ホスティング先が必要です。

代表的な選択肢は次のとおりです。

・Azure App Service
・IIS
・Docker
・Linuxサーバー
・AWSやGoogle Cloud

デプロイ時には、次の点も確認します。

・本番用DBの接続文字列
・HTTPS設定
・環境変数
・ログ出力先
・CORS設定
・認証、認可
・Swaggerの公開範囲

開発環境で動くだけでなく、本番環境で安全に運用できる設計が重要です。

10-6. 次に学ぶべきC# WebAPIの学習ステップ

CRUD APIとDB連携まで理解できたら、次は以下を学ぶとよいでしょう。

・Service層、Repository層の設計
・DTOとAutoMapper
・JWT認証
・例外ハンドリングミドルウェア
・ログ設計
・単体テスト
・統合テスト
・Docker化
・Azureへのデプロイ
・CI/CD

C# WebAPIは、基本を押さえたあとに設計、セキュリティ、運用まで学ぶことで、実務レベルに近づけます。

まとめ

C# WebAPIを作るなら、ASP.NET Core Web APIを使うのが基本です。

この記事では、C# WebAPIの概要から、開発環境の準備、Swaggerの使い方、CRUD APIの実装、Entity Framework CoreによるDB連携、実務を意識した設計ポイントまで解説しました。

重要なポイントを振り返ると、次のとおりです。

・C# WebAPIはHTTP経由でデータをやり取りする仕組み
・ASP.NET Core Web APIを使うとC#で効率よくAPIを作れる
・Swaggerを使うとブラウザからAPIをテストできる
・CRUDはGET、POST、PUT、DELETEで実装する
・Entity Framework Coreを使うとDB連携がしやすい
・実務ではDTO、DI、非同期処理、エラー設計、セキュリティが重要

初心者は、まず小さなCRUD APIを作り、Swaggerで動作確認し、次にDB連携へ進むのがおすすめです。

この流れを理解できれば、C# WebAPI開発の土台がしっかり身につきます。