Add Overview (#3)

README.md

@@ -1,2 +1,37 @@
-# qiita-openapi
-Qiita OpenAPI
+# Qiita API v2 OpenAPI
+
+このリポジトリは以下のドキュメントから作成したものです。
+
+<https://qiita.com/api/v2/docs>
+
+## CI
+
+CIには `spectral` を使用しています。
+
+<https://github.com/stoplightio/spectral>
+
+## License
+
+```plain
+MIT License
+
+Copyright (c) 2024 nanato12
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```

openapi.yml

@@ -2,15 +2,85 @@ openapi: 3.0.0
 info:
   title: Qiita API v2
   version: 0.0.1
-  description: This document describes the Qiita API v2 specification.
+  description: |
+    ## 概要
+
+    このドキュメントではQiita API v2の仕様について説明します。
+
+    ## リクエスト
+
+    APIとの全ての通信にはHTTPSプロトコルを利用します。アクセス先のホストには、Qiitaのデータを利用する場合には `qiita.com` を利用し、Qiita Teamのデータを利用する場合には `*.qiita.com` を利用します ( `*` には所属しているTeamのIDが入ります)。
+
+    ## パラメータ
+
+    API v2へのリクエストには、GET、POST、PUT、PATCH、DELETEの5種類のHTTPメソッドを利用します。多くのAPIへのリクエストにはパラメータを含められますが、GETリクエストにパラメータを含める場合にはURIクエリを利用し、それ以外の場合にはリクエストボディを利用します。パラメータには、ページネーション用途など任意で渡すものと、投稿時の本文など必須のものが存在します。APIドキュメントには、各APIごとに送信可能なパラメータが記載されています。
+
+    ## 利用制限
+
+    認証している状態ではユーザーごとに1時間に1000回まで、認証していない状態ではIPアドレスごとに1時間に60回までリクエストを受け付けます。
+
+    ## シングルサインオンを利用中のチームについて
+
+    シングルサインオンによる認証のみを許可しているQiita Teamのチームでは、セキュリティ上の理由から、チーム別アクセストークンでのみAPIを利用したアクセスが可能です。
+
+    ## ステータスコード
+
+    200、201、204、400、401、403、404、500の8種類のステータスコードを利用します。GETまたはPATCHリクエストに対しては200を、POSTリクエストに対しては201を、PUTまたはDELETEリクエストに対しては204を返します。但し、エラーが起きた場合にはその他のステータスコードの中から適切なものを返します。
+
+    ## データ形式
+
+    APIとのデータの送受信にはJSONを利用します。JSONをリクエストボディに含める場合、リクエストのContent-Typeヘッダにapplication/jsonを指定してください。但し、GETリクエストにバラメータを含める場合にはURIクエリを利用します。また、PUTリクエストまたはDELETEリクエストに対してはレスポンスボディが返却されません。日時を表現する場合には、[ISO 8601](http://ja.wikipedia.org/wiki/ISO_8601) 形式の文字列を利用します。
+
+    ```
+    GET /api/v2/items?page=1&per_page=20 HTTP/1.1
+    ```
+
+    ## エラーレスポンス
+
+    エラーが発生した場合、エラーを表現するオブジェクトを含んだエラーレスポンスが返却されます。このオブジェクトには、エラーの内容を説明するmessageプロパティと、エラーの種類を表すtypeプロパティで構成されます。typeプロパティはエラーの種類ごとに一意な文字列で、`^[a-z0-9_]+$` というパターンで表現できます。
+
+    ```
+    {
+      "message": "Not found",
+      "type": "not_found"
+    }
+    ```
+
+    ## ページネーション
+
+    一部の配列を返すAPIでは、全ての要素を一度に返すようにはなっておらず、代わりにページを指定できるようになっています。これらのAPIには、1から始まるページ番号を表すpageパラメータと、1ページあたりに含まれる要素数を表すper_pageパラメータを指定することができます。pageの初期値は1、pageの最大値は100に設定されています。また、per_pageの初期値は20、per_pageの最大値は100に設定されています。
+
+    ページを指定できるAPIでは、[Linkヘッダ](http://tools.ietf.org/html/rfc5988) を含んだレスポンスを返します。Linkヘッダには、最初のページと最後のページへのリンクに加え、存在する場合には次のページと前のページへのリンクが含まれます。個々のリンクにはそれぞれ、first、last、next、prevという値を含んだrel属性が紐付けられます。
+
+    ```
+    Link: <https://qiita.com/api/v2/users?page=1>; rel="first",
+          <https://qiita.com/api/v2/users?page=1>; rel="prev",
+          <https://qiita.com/api/v2/users?page=3>; rel="next",
+          <https://qiita.com/api/v2/users?page=6>; rel="last"
+    ```
+
+    また、ページを指定できるAPIでは、要素の合計数が `Total-Count` レスポンスヘッダに含まれます。
+
+    ```
+    Total-Count: 6
+    ```
+
+    ## JSON Schema
+
+    Qiita API v2では、APIのインターフェースを定義したJSON-Schemaを提供しています。このスキーマでは、APIでどのようなリソースが提供されているか、それらはどのようなプロパティを持っているか、それらがどのように表現されるか、及びどのような操作が提供されているかといった事柄が定義されています。スキーマには、次のURLでアクセスできます。
+
+    - https://qiita.com/api/v2/schema
+    - https://qiita.com/api/v2/schema?locale=en
+    - https://qiita.com/api/v2/schema?locale=ja
   contact:
     name: nanato12
     url: 'https://github.com/nanato12'
     email: admin@okj.info
+  termsOfService: 'https://github.com/nanato12/qiita-openapi'
 servers:
   - url: 'https://qiita.com'
     description: When using data from Qiita
-  - url: 'https://*.qiita.com'
+  - url: 'https://{team_id}.qiita.com'
     description: When using Qiita Team data
 security:
   - Bearer: []