初めてOpenAPIを触ったお話
こんにちは。ねこがくれです。
今日はOpenAPIというフレームワークを初めて触った時の感想や改善点などまとめていこうと思います。
そもそもOpenAPIってなんぞや
私も先週までその存在を知りませんでした。
ココによると
OpenAPIは、REST API の API 記述形式です。OpenAPI ファイルを使用すると、次の内容を含む API 全体を記述できます。
利用可能なエンドポイント(/users)と各エンドポイントでの操作(GET /users、POST /users)
操作パラメータ 各操作の入力と出力
認証方法
- 連絡先情報
- ライセンス、
- 利用規約、
- その他の情報。
API 仕様は YAML または JSON で記述できます。この形式は学習しやすく、人間と機械の両方にとって読みやすいものです。完全な OpenAPI 仕様は GitHub で確認できます: OpenAPI 3.0 仕様
ということらしいです。
はて?REST APIってなんだ?って私は思いました。まずはそこからです。
REST APIとは
私はこの記事を参考にして勉強しました。
つまるところ、
GET https://api.scratch.mit.edu/users/sei6sei/
とかのGET
の部分のことです。
正直OpenAPIでめちゃくちゃ簡単なAPI規格だけ作るとかなら細かく勉強しなくていいと思いました。
エンジニアとか開発者の人でPOSTメソッドやGETメソッドを使ったことがない人はあまりいないと思うので大体わかってる方が多いと思います。
OpenAPIで何を作った?
私がOpenAPIを勉強したのには、私が所属している団体が運営しているSNSが現在APIベースで動いておらず、直接DBに書き込んでいます。
なので、APIを使った仕様に一気に刷新しよう!スマホアプリ化も難しいし!ということになったのでAPIを作ることになりました。
そして、細かい詳細は偉大なるChatGPT君にアイデアを出してもらい、yaml形式に落とし込んだのがこれです。
一部抜粋すると、
openapi: 3.0.0
info:
title: TalkNeT API
version: 1.0.0
description: TalkNeTのAPI
paths:
/posts:
post:
summary: newPost
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
sessionId:
type: string
content:
type: string
required:
- sessionId
- content
responses:
'201':
description: Post success
content:
application/json:
schema:
type: object
properties:
postId:
type: string
'401':
description: Auth failed
こういう感じです。
これを書いているときに一度地獄を見ました。
私は基本、VScodeで作業しているのですが、とくに
content:
application/json:
schema:
type: object
properties:
sessionId:
type: string
content:
type: string
required:
- sessionId
- content
の部分で挫折しました。
なぜなら、(今となっては馬鹿でしかないですが)このサイトを使っていなかったからです。
それまではいろんなサイトを参考にしながら、あってる!?あってる!?この書き方でいいのかこれ!? と、頭でひたすら実行(というよりかはビジュアル化)させながら書いてたのでここで二時間ぐらい空費してしまいました...。
これはおかしいと思い色々調べてやっと、このサイトの存在を知ったわけです。
最後に
OpenAPIは全体的にとても使いやすく定義もしやすいので今後も重宝しそうです...。
これからOpenAPIさわるよ~という方は「絶対に」このサイト、もしくはVScodeの拡張機能を使いましょう。本当に地獄を見ます。
最後まで読んでくださってありがとうございます。では。
Discussion
VSCode ExtensionでOpenAPI (Swagger) Editorというものがあります。
デフォルトでSwagger UIによるプレビューが使えるので、Swagger Editorと同程度のエラーチェックはできるかと。
他にRedocによるプレビューもできます。
なお、必須ではないものの、
post:
等) にはoperationId
を指定するschema:
)のうち、type: object
であるものはすべてcomponents
に切り出して$ref
で参照するをしておくと、自動生成コードが使いやすくなります。
Swagger Editorのメニューにも
Generate Server
やGenerate Client
がありますが、他にもOpenAPI Generatorや言語ごとに特化したコード生成ツールがあります。上記の適用例
※OpenAPI 3.0系最新の3.0.4だとSwaggerがエラーを吐くので3.0.3にしています。
コメントありがとうございます。
参考にさせていただきます!