freks blog

API Documentのために OpenAPI3 を使ってみました
Swaggerはビジネス色が強くなってしまったため、OpenAPI3に分離したという認識（どこかで読んでそうだったはず..）

また Rails で committee gem を使って API の形が正しいか rspec でテストがかきたくてはじめました

Stoplight Studio

OpenAPI3のフォーマットを読んで書いていくのは大変なので

Stoplight Studio | OpenAPI Design, Planning & Modeling Tool

を使いました
ブラウザ上でも使えるしアプリもあります

GUIで定義をしていくと OpenAPI3 になるので便利です

committee gem

Rails + committee gem でAPIドキュメントが古くならないようにテストいれました

参考) OpenAPI3.0を導入してみました - アクトインディ開発者ブログ

必須でないフィールドでもnullが入ってくるとエラーになる

Stoplight Studioで定義して、required: falseにしていてもnullが入るとエラーになる
OpenAPI3から、nullable: trueができたので設定してやるといい
Stoplight Studioで設定できないので、手動で追記する

"user": {
  "title": "user",
  "type": "object",
  "properties": {
    "client_lawyer_type": {
      "type": "string",
      "nullable": true
    }
  }
}

未定義のフィールドがあるとエラーにする

stoplight studioで定義を作成すると、フィールドが追加されてもエラーにならない
"additionalProperties": false を手で追記するとエラーにできる

{
  "type": "object",
  "properties": {
    "foo": {
      "type": "string"
    },
    "bar": {
      "type": "number"
    },
  },
  "additionalProperties": false
}

参考リンク

• OpenAPI 3 Tutorial| SwaggerHub