Swagger (Open API）3.0 がリリースされてから初めて使う機会があったので、自分なりの記述のポイントと、記述例をまとめました。

リソースIDやリソースといった複数のAPIで使われるプロパティ・オブジェクトを components/schemas に定義する。
リソースIDのようなリクエストには指定しないが、レスポンスには指定されるプロパティは readOnly: true で表現する。
個別取得APIでは返却されるが、一覧取得APIでは返却されないプロパティは、スキーマを分離して allOf を指定して共通のプロパティを定義する。
ページングや検索などの複数のAPIで使われるパラメータを components/parameters に定義する。
エラーレスポンスの形式が共通である場合は components/responses に定義し、エラーコードを description に表形式でまとめる。

Swaggerを編集するときは、Swagger Viewer（Visual Studio Codeプラグイン）が、リアルタイムプレビューに対応していて、かつ動作も軽いため使いやすい。