この記事は株式会社TRAILBLAZER Advent Calendar 2024 の10日目の記事です。

こんにちは、株式会社TRAILBLAZERでテックリードをしております @joy04d です。

最近は、寒さと運動不足対策としてエアロバイクを漕ぎながら仕事していたり、十数年ぶりに続編がリリースされた某ゲームを、苦境の中リリースしてくれた開発陣に感謝の正拳突きをしながらプレイしたりしております(=ω=)

WESTERの紹介

そんな私ですが、普段のお仕事では、主にJR西日本のプロダクトであるWESTERアプリの開発チームとして働いております。

このプロダクトについて軽く紹介させて頂くと、JR西日本グループのサービスを利用される方々の日常に寄り添うアプリとして、

時刻表・運行情報確認や経路検索といった移動ナビの機能を備えていたり
JR西日本グループの提供するWESTERポイントを貯める・使うための各種機能を備えるポイントアプリとしての機能もあったり
JR西日本グループが提供する様々なサービスへの入口としてのポータルアプリという側面もある

という複合的なプロダクトとなっています。

さて、この辺りからが本題なのですが、お察しの通りこれらの多様な機能が1システム上ですべて実装されているわけではありません。様々なシステム間をAPIで相互連携することで実現されています。

そしてAPI連携に欠かせないものといえばAPI仕様書。

このAPI仕様書を統一規格で書きたいと思ったときに出てくるのが、タイトルにもあるOpenAPIになります(=ω=)

OpenAPIの紹介

OpenAPIとは、REST APIのインターフェイス定義の記述仕様(APIスキーマ)になります。

正式にはOpenAPI Specification(OpenAPI仕様)と呼ばれるもので、元々はSwagger Specificationという名前でしたが、Linux Foundation他名だたる企業の支援のもとに標準化されるにあたって、名称が変更になりました。

少しややこしいのですが、元になったSwagger仕様の提供元から、歴史的経緯で今もSwaggerの名前でツール群が提供されているため、OpenAPI仕様を元にした → Swaggerツール群が今もある、みたいに覚えておくと多少混乱しにくいかもしれません🤔

今のところ、REST APIの記述仕様としてはデファクトスタンダードと言って良いものになります(=ω=)

基本編

記法としては、YAMLかJSONを用いることができます。

YAMLでサンプルを挙げてみると

openapi: 3.0.0
info:
  title: Sample API
  description: Optional multiline or single-line description in [CommonMark](http://commonmark.org/help/) or HTML.
  version: 0.1.9

servers:
  - url: http://api.example.com/v1
    description: Optional server description, e.g. Main (production) server
  - url: http://staging-api.example.com
    description: Optional server description, e.g. Internal staging server for testing

paths:
  /users:
    get:
      summary: Returns a list of users.
      description: Optional extended description in CommonMark or HTML.
      responses:
        "200": # status code
          description: A JSON array of user names
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string

のような形で記載すれば、Swagger UIを用いて

のような仕様書をすぐに起こすことができます。

基本構造についてはこちらをさらっと眺めつつ、web上で試せるEditorも提供されているので、軽く触って頂ければよりイメージは掴みやすいかと思います(=ω=)

ちょっとだけ応用編

データ型としては、JSONSchemaを基準に、string,number,integer,booleanなどの基本型に対してvalidationとして

min - max の length指定
'^\d{3}-\d{2}-\d{4}$' のようなpattern指定
dateやdate-timeなどのformat指定

などが可能です。

また、共通部分をコンポーネント化することが可能で、例えば

ことなどができます(=ω=)

で、何が嬉しいの？

構造化データである、これに尽きると思います。
これにより

します。
自前で活用することもできますし、他にも様々なツールが作成されたりしているので、気になる方は公式のリストを覗いてみてください(=ω=)

さらなる世界へ

さらに言うと、これらを活用すれば、先にAPIスキーマを定義して、その定義を元に各ツール群で自動化を行いながらバックエンド・フロントエンドを並行的に開発する手法を取ることができるようになります。これはスキーマ駆動開発と呼ばれていたりします。
(OpenAPI Generatorの中の人の解説がわかりやすいので、参考まで)

部分的な活用でも十分に効果がありますが、ここまで活用できれば、より幸せな世界が待っているかもしれません(=ω=)

最後に

今回はOpenAPIの紹介をさせていただきました。
ご笑覧いただければ幸いです。

初期の学習コストや時々ハマリポイントがあったり、PJの途中から導入するのは中々骨だったりしますが、それらを超えれば十分なリターンが得られる技術だと思います。ぜひ検討してみてください。

また、より幸せな世界を目指して一緒に進む仲間を募集したりもしています。
最後に貼り付けておりますので、興味持っていただけた方は確認頂ければより嬉しいです。

ここまでありがとうございましたm(_ _)m