◆ Live配信スケジュール ◆
サイオステクノロジーでは、Microsoft MVPの武井による「わかりみの深いシリーズ」など、定期的なLive配信を行っています。
⇒ 詳細スケジュールはこちらから
⇒ 見逃してしまった方はYoutubeチャンネルをご覧ください

【4/18開催】VSCode Dev Containersで楽々開発環境構築祭り〜Python/Reactなどなど〜
Visual Studio Codeの拡張機能であるDev Containersを使ってReactとかPythonとかSpring Bootとかの開発環境をラクチンで構築する方法を紹介するイベントです。
https://tech-lab.connpass.com/event/311864/

こんにちは、サイオステクノロジーの佐藤陽です。

今回はAzureFunctionsで実装したAPIを簡単にSwaggerドキュメントにおこせるExtensionをご紹介します。
その名もAzure Functions OpenAPI Extensionです！

便利すぎて、一度使えばやみつきになるツールなので是非活用してみてください。

ちなみにこちら、Microsoftのカンファレンスでも紹介されたMSお墨付きの便利ツールです。
興味ある方はぜひこちらもご覧ください。

1 はじめに
2 OpenAPI/Swaggerとは？
3 実際に作ってみよう！
4 おまけ
- 4.1
5 まとめ

はじめに

APIを開発しているエンジニアのみなさん。
APIの仕様書って作っていますか？メンテナンスしていますか？

実装に追われ、仕様書を作る暇がない
一度作ったはいいけど、APIに入った修正を仕様書に反映できてない

なんてことありませんか？

また仕様書はどうやって作成していますか？
エクセル仕様書でしょうか？バージョン管理はできているでしょうか？

そんな問題を一気に解決するのが、今回ご紹介するAzureFunctions OpenAPI Extensionsです。
実装に少し修正を加えるだけでSwagger仕様書が作成されます。

また、実装コードに合わせて仕様書部分のコードも記載するため
バージョン管理が簡単に行え、メンテナンス性にも優れます。

OpenAPI/Swaggerとは？

OpenAPI?Swagger?なにそれ？という方もいらっしゃるかと思うので簡単にご紹介します。

簡単に言ってしまうと、REST APIの仕様書を作成するための仕様およびツールです。
サンプルを見せると、このような画面のものです。

見たことある方も多いのではないでしょうか？

また、よくOpenAPIとSwaggerの違いについて言及されることがありますが

OpenAPI：仕様書を記述する仕様
Swagger：OpenAPI仕様に基づいたものを実装するツール

という定義になります。
詳細に関してはSwagger公式に記載があるので興味のある方はこちらをご覧ください。

実際に作ってみよう！

準備編

仕様書を作るためにはまずAPIが必要となってくるため、プロジェクトを用意します。

今回はVisualStudio上でAzureFunctionsのテンプレートを利用してプロジェクトを作成します。
実行環境は.NET 6で進めていきます。

プロジェクトが作成されると、サンプル関数が一つ存在しているかと思います。
今回はこれを少し修正して、以下のような関数を一つ作成しました。

public static class Function
{
    [FunctionName("GetName")]
    public static async Task<IActionResult> Run(
        [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post", Route = "{country}/names")] HttpRequest req,
        string country, ILogger log)
    {
        log.LogInformation("C# HTTP trigger function processed a request.");


        string name = req.Query["name"];


        string requestBody = await new StreamReader(req.Body).ReadToEndAsync();
        dynamic data = JsonConvert.DeserializeObject(requestBody);
        name = name ?? data?.name;


        if (string.IsNullOrEmpty(name))
        {
            return new BadRequestObjectResult("Name parameter not found");
        }
        else
        {
            return new OkObjectResult($"Hello, {name} from {country}. This HTTP triggered function executed successfully.");
        }
    }
}

早速実行してみましょう！

すると、コンソールログが表示され、API実行のためのエンドポイントが一つ表示されます。
適当にパラメータを追加して、APIをブラウザで実行すると…

localhost:7135/api/japan/names?name=sios

正しく実行できていることが確認できます。

ひとまずこれでAPIの動作自体はOKですね。
では実際にこのAPIをSwaggerドキュメントに起こしていきたいと思います。

Extensionのインストール

VisualStudioのNuGetコンソールから以下二つのExtensionをインストールします。

Microsoft.Azure.WebJobs.Extensions.OpenApi
Microsoft.Azure.WebJobs.Extensions.OpenApi.Core

APIの仕様を追記

では次に、作成したAPIの仕様を記載していきます。

FunctionNameのAttribute下に以下のようなAttributeを加えます。

[FunctionName("GetName")]
//以下を追加
[OpenApiOperation(operationId: "GetName", tags: new[] { "name" }, Summary = "Gets the name", Description = "This gets the name.", Visibility = OpenApiVisibilityType.Important)]
[OpenApiParameter(name: "name", In = ParameterLocation.Query, Required = false, Type = typeof(string), Summary = "The name", Description = "Enter Your name", Visibility = OpenApiVisibilityType.Important)]
[OpenApiParameter(name: "country", In = ParameterLocation.Path, Required = true, Type = typeof(string), Summary = "The country", Description = "Enter your country", Visibility = OpenApiVisibilityType.Important)]
[OpenApiResponseWithBody(statusCode: HttpStatusCode.OK, contentType: "text/plain", bodyType: typeof(string), Summary = "The response", Description = "Success")]
[OpenApiResponseWithBody(statusCode: HttpStatusCode.BadRequest, contentType: "text/plain", bodyType: typeof(string), Summary = "The response", Description = "Fail")]
//ここまで
public static async Task<IActionResult> Run(
[HttpTrigger(AuthorizationLevel.Anonymous, "get", "post", Route = "{country}")] HttpRequest req,

それぞれのAttributeを簡単に説明すると

OpenApiOperation	このAPIに対する概要情報を示しています。どんなAPIなのかを記載したり、タグ付けしてSwagger上でグループ分けを行えたりします。
OpenApiParameter	リクエストパラメータです。クエリパラメータなのか、パスパラメータなのか、どういった値なのかの記述を行う事ができます必須パラメータなのか、任意のパラメータなのかも指定できます。
OpenApiResponseWithBody	レスポンスパラメータです。このAPIがどのような値を返すのかを定義します。複数指定することも可能で、成功した場合や失敗した場合にどのような値が返されるかの記述を行うことができます。