LY Corp Tech Blog公式発表·2026年3月3日 11:00·約1分

Swaggerを使用したAPIドキュメント作成とバックエンド・フロントエンド間の連携

#API開発 #Swagger #OpenAPI #バックエンド開発 #フロントエンド開発 #開発効率化

整理・翻訳:ainew.jp 編集システムAIによる自動処理作り方と限界

本文の状態

日本語全文を表示中

詳細モードで約1分の本文を読めます。

同じ出来事の情報源

この情報源を基点に整理

LY Corp Tech Blog

まず要点

LINE Growth Technology福岡チームが、Swaggerツールを使用してAPIドキュメントを作成し、バックエンドとフロントエンドの開発効率を向上させる方法を解説している。

Source Article

元記事を日本語で読む

本文に関係しない購読案内、埋め込み通知、サイト内プロモーションは除いています。

この記事は、合併前の旧ブログに掲載していた記事（初出：2020年11月25日）を、現在のブログへ移管したものです。内容は初出時点のものです。

こんにちは。LINE Growth Technology福岡...

原文を表示

この記事は、合併前の旧ブログに掲載していた記事（初出：2020年11月25日）を、現在のブログへ移管したものです。内容は初出時点のものです。

こんにちは。LINE Growth Technology福岡開発室でサーバーサイドエンジニアをしている中村です。

この記事では担当していたプロジェクトで実施した、Swaggerを使ったAPIドキュメントの作成と、BE（バックエンド）とFE（フロントエンド）間の連携について紹介します。

プロジェクトの説明

はじめに、今回LINE Growth Technology福岡開発室（以下「GT」）がシステムの設計開発を担当した、LINE公式アカウント審査ツールのプロジェクトについて説明します。

LINE公式アカウント審査ツールとは、LINE公式アカウントで認証済アカウントが申請された際に、申請内容が適切であるか審査するシステムです。**このシステムは、LINE公式アカウントが利用されている各国に存在する審査パートというチーム（以下「審査チーム」）によって利用され、日本以外の国家も含め、一日あたり平均約1,000件の申請を審査します。

プロジェクトの開発は大きくわけて、審査チームが使用するWEB画面を提供するFEと、WEB画面及び他システムにAPIを提供するBEが存在します。

今回私はBE担当としてこのプロジェクトに参加しました。

先述の通り、BEはAPIを用いてFE及び他システムと連携するため、APIの作成にあたり次の課題がありました。

APIドキュメントを作る必要がある
APIドキュメントを手動管理するコストをかけられない
FEとBEの開発時期が重なっている
FEのスムーズな開発のため、素早くAPIを定義しなければならない

以上の課題を解決するために、手動ではなく自動でAPIドキュメントを作成する方法を調べたところ、Swaggerで実現可能であることがわかりました。

SwaggerとはOAS（OpenAPI Specification。REST APIの仕様を定義するフォーマット。）に基づくツールセットであり、以下の機能で構成されます。

Swagger Editor: OASを作成する
Swagger UI: OASからHTMLドキュメントを作成する
Swagger Codegen: OASから各言語のコードを作成する

Swaggerの導入

OASの設定

GTのBE開発では、主にJavaのSpring Frameworkを使用しています。

そしてSpring Foxというサードパーティのライブラリを組み合わせることで、Spring FrameworkのコードからOASを作成することができます。

http://springfox.github.io/springfox/

ソースコード上のAPIエンドポイントやリクエスト・レスポンスモデルにSpring Foxのアノテーションを付与することで、OASの内容を設定します。

OAS設定**

code

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.regex("/api.*"))
                .build()
                .useDefaultResponseMessages(false);
    }
}

@Data
@ApiModel(description = "Pet")
public class Pet {

    @ApiModelProperty(value = "ID", example = "1")
    private int id;

    @ApiModelProperty(value = "名前", example = "Name")
    private String name;
}

@RestController
@RequestMapping("/api/pet")
public class PetController {

    @ApiOperation("Petを取得")
    @ApiResponse(code = 200, message = "Pet", response = Pet.class)
    @GetMapping("/{id}")
    public Pet getPet(
            @ApiParam(value = "PetのID", required = true, example = "1") @PathVariable int id) {
        // TODO: 実装
        return new Pet();
    }

    @ApiOperation("Petを作成")
    @PostMapping
    public void createPet(@ApiParam(value = "Pet", required = true) Pet pet) {
        // TODO: 実装
    }

    @ApiOperation("Petを更新")
    @PutMapping("/{id}")
    public void updatePet(@ApiParam(value = "PetのID", required = true, example = "1") @PathVariable int id,
                          @ApiParam(value = "Pet", required = true) @RequestBody Pet pet) {
        // TODO: 実装
    }

    @ApiOperation("Petを削除")
    @DeleteMapping("/{id}")
    public void deletePet(@ApiParam(value = "PetのID", required = true, example = "1") @PathVariable int id) {
        // TODO: 実装
    }
}

これでアプリケーションを起動してhttp://localhost:8080/v2/api-docsにアクセスすると、OASを確認できるようになりました。

OASファイルを作成

WEB上で確認できるようになったOASをGithubで管理するため、OASをファイルに保存できるようにします。**OASを確認するにはアプリケーションを起動中でなければいけないので、OASをダウンロードしてファイルに保存する処理をテストコードとして書きます。

OASファイル作成**

code

 FileUtils.writeStringToFile(
                        new File("build/docs/oas.json"),
                        new String(result.getResponse().getContentAsByteArray(), StandardCharsets.UTF_8)));
    }
}

このテストを実行すると、OASをファイルに保存できます。

OASファイル

code

$ ./gradlew test --tests GenerateOasFile

$ cat bulid/docs/oas.json
{
    "swagger": "2.0",
    "info": {
        "description": "Api Documentation",
        "version": "1.0",
        "title": "Api Documentation",
        "termsOfService": "urn:tos",
        "contact": {},
        "license": {
            "name": "Apache 2.0",
            "url": "http://www.apache.org/licenses/LICENSE-2.0"
        }
    },
    "host": "localhost",
    "basePath": "/",
    "tags": [
        {
            "name": "pet-controller",
            "description": "Pet Controller"
        }
    ],
    "paths": {
        "/api/pet": {
            "post": {
                "tags": [
                    "pet-controller"
                ],
                "summary": "Petを作成",
                "operationId": "createPetUsingPOST",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "*/*"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "query",
                        "description": "ID",
                        "required": false,
                        "type": "integer",
                        "format": "int32",
                        "x-example": 1
                    },
                    {
                        "name": "name",
                        "in": "query",
                        "description": "名前",
                        "required": false,
                        "type": "string",
                        "x-example": "Name"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                },
                "deprecated": false
            }
        },
        "/api/pet/{id}": {
            "get": {
                "tags": [
                    "pet-controller"
                ],
                "summary": "Petを取得",
                "operationId": "getPetUsingGET",
                "produces": [
                    "*/*"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "description": "PetのID",
                        "required": true,
                        "type": "integer",
                        "format": "int32",
                        "x-example": 1
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/Pet"
                        }
                    }
                },
                "deprecated": false
            },
            "put": {
                "tags": [
                    "pet-controller"
                ],
                "summary": "Petを更新",
                "operationId": "updatePetUsingPUT",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "*/*"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "description": "PetのID",
                        "required": true,
                        "type": "integer",
                        "format": "int32",
                        "x-example": 1
                    },
                    {
                        "in": "body",
                        "name": "pet",
                        "description": "Pet",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/Pet"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                },
                "deprecated": false
            },
            "delete": {
                "tags": [
                    "pet-controller"
                ],
                "summary": "Petを削除",
                "operationId": "deletePetUsingDELETE",
                "produces": [
                    "*/*"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "description": "PetのID",
                        "required": true,
                        "type": "integer",
                        "format": "int32",
                        "x-example": 1
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                },
                "deprecated": false
            }
        }
    },
    "definitions": {
        "Pet": {
            "type": "object",
            "properties": {
                "id": {
                    "type": "integer",
                    "format": "int32",
                    "example": 1,
                    "description": "ID"
                },
                "name": {
                    "type": "string",
                    "example": "Name",
                    "description": "名前"
                }
            },
            "title": "Pet",
            "description": "Pet"
        }
    }
}

OASファイルの自動作成とAPIドキュメント公開

OASファイルをGithubで管理します。**今回はCircleCIを使用して、APIが更新されるようなPull Requestをmasterブランチにmergeするとき、自動でOASファイルを作成してpushするようにしました。

CircleCI**

code

version: 2
jobs:
  update_doc:
    docker:
      - image: openjdk:11
        name: jdk
    steps:
      - checkout
      - run: ./gradlew test --tests GenerateOasFile
      - run: bash .circleci/update-oas.sh

workflows:
  version: 2
  update_doc:
    jobs:
      - update_docs:
          filters:
            tags:
              only: /.*/
            branches:
              only: master

update-oas.sh

code

#!/bin/bash

git pull origin master

SRC_DIR="build/docs"
DST_DIR="docs"
DIFF=$(diff -qr "$SRC_DIR" "$DST_DIR")
if [ -z "$DIFF" ]; then
    exit 0
fi

rm -rf "$DST_DIR"
cp -r "$SRC_DIR" "$DST_DIR"

git add "$DST_DIR"
git config user.email "email@example.com"
git config user.name "name"
git commit -m "Update docs"
git push origin master

そして、作成したOASファイルとSwagger UIをGithub Pagesに公開することで、WEB上でAPIドキュメントをHTMLとして閲覧できるようになりました。

OASを通じてFEとBEの連携

OASからFEのコードを作成します。**FEはTypeScriptを使ってWeb画面を開発していますが、サードパーティライブラリのswagger-to-tsを使用することで、OASからTypeScript型定義を作成できます。

swagger-to-ts**

code

 schema.ts [1ms]

$ cat schema.ts
/**
 * This file was auto-generated by swagger-to-ts.
 * Do not make direct changes to the file.
 */

declare namespace OpenAPI2 {
  export interface Pet {
    /**
     * ID
     */
    id?: number;
    /**
     * 名前
     */
    name?: string;
  }
}

効果、メリット

Swaggerを導入することで、最初に挙げたプロジェクトの課題を解決することができました。

APIドキュメントはソースコードから作成されるようになり、CircleCIで常に最新の状態が維持されるため、手動で管理する必要はなくなりました。

APIドキュメントはFEとBEのコミュニケーションの基準になるので、それが正しく管理されていることで円滑なコミュニケーションを取ることもできました。

FEとBEの開発期間が重なっているため素早くAPIを定義しなければいけない件についても、BEがAPIの内部実装をする前にエンドポイントやリクエスト・レスポンスモデルの設定だけ済ませてしまえばOASを作成できるため、FEはBEのAPI実装を待たずスピーディに開発を進められたと感じます。

そして予定外だったメリットは、OASからType Script型定義を作成できたことです。

Type Script型定義はFEにとって大変な手間だったようで、それをOASから作成することでFEの負担を大きく軽減できたとのことです。

反省点、新たな課題

以上の有効な効果を得られたましたが、いくつかの反省点もありました。

ます、Spring Foxのアノテーションです。

簡単なOASを作成するには最低限のアノテーションを設定すれば良いのであまり手間がかからないのですが、詳細のものを作ろうとするとアノテーションを多く設定する必要があり多少の手間がかかりました。

また、導入初期はアノテーションの種類を完全に把握できていなかったことも一因です。

しかし慣れてしまえば簡単な仕組みですし、一部を設定すればあとはコピー&ペーストできる部分も多いため、経験と事前学習で対応可能かと思います。

そして、OASから作成するTypeScript型定義が完全ではないことです。

swagger-to-tsを使用してTypeScript型定義を作成しましたが、定義されるのはリクエスト・レスポンスモデルの型だけで、APIのURLパラメータは定義されませんでした。

そのため、いくつかのURLパラメータは手動で型定義することになりました。

型定義を完全に自動作成するのであれば、swagger-to-tsの詳細な使用方法の調査や、swagger-to-ts以外のツールを使用することも検討する必要があります。

最後に

以上、APIドキュメントの作成と、FEとBE間の連携という課題に対する、Swagger導入の体験について書かせていただきました。

ドキュメントは作成・管理するコストに対してリターンが小さい上に、正しく管理されていなければ誤った記述が残されて混乱を招くため敬遠されがちです。

それでも、ソースコードからの作成や自動管理など工夫することで、そのハードルをある程度は下げられたと感じます。

新たな課題はありますが、コスト以上のリターンを得ることができましたので、他のプロジェクトでも是非導入をすすめたいと思います。

この記事をシェア

今日のまとめ

AIデイリーブリーフで今日の重要ニュースをまとめ読み

Swaggerを使用したAPIドキュメント作成とバックエンド・フロントエンド間の連携

元記事を日本語で読む

プロジェクトの説明

Swaggerの導入

OASファイル

update-oas.sh

効果、メリット

反省点、新たな課題

最後に

調べる

選ぶ

サイト