基本情報

参考記事: https://riotz.works/articles/lopburny/2019/07/21/efficient-way-to-manage-api-definition/ REST APIについて理解していることが前提。 RESTfulな設計に基づいている。 ソースコード修正と同時に定義の修正も行うため（行うはず）設計書が常に最新である。

■形式 「YAML」「JSON」の2形式に対応。 「YAML」の方が読み書きしやすいのでおすすめです。 「YAML」はコメントを記述できる。

■「Swagger UI」OR「Redoc」（公開）どちらが良い？ ・Redoc OpenAPI（Swagger）仕様を基にして、APIのドキュメントを生成するためのツール。

Swagger UI

GitHubからダウンロードして自分のサーバーに設置する。 https://github.com/swagger-api/swagger-ui

cd /usr/local/src
# ここに配置
unzip swagger-ui-master.zip
mkdir /var/www/html/swagger-ui
cp -r swagger-ui-master/dist /var/www/html/swagger-ui
# 既にLaravelがある場合は コピー先Laravelプロジェクトのpublic

# Apache設定ファイル作成
# ドキュメントルートに設定
vi /etc/httpd/conf/httpd.conf

yaml

# ひな形
openapi: 3.0.0
info:
  title: サンプルAPI
  description: サンプルAPIになります。
  version: 1.0.0
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Access token for API

# 下部
servers:
  - url: https://google.com
paths:
  /api/v1/users:
    get:
      summary: ユーザ一覧 取得
      security:
        - bearerAuth: []  # ここでBearerトークンを要求
      parameters:
        - in: path # パラメータの設定箇所「in: path」or「in: query」
      requestBody:
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  user_id:
                    type: integer
                    description: ユーザID
                    example: 100

with Laravel

# swagger-php 導入
composer require zircote/swagger-php

# OpenAPI yaml出力（下記の場合はLaravelプロジェクトのディレクトリでコマンド実行）
./vendor/bin/openapi app -o openapi.yaml

use OpenApi\Attributes as OA;

#[OA\Info(title: "Sample API", version: "0.1")] // Info 必須
#[OA\Server(url: "http://localhost:8080")]
class SampleController extends Controller
{
  #[OA\Get(path: '/sample')] // HTTPメソッド 必須
  #[OA\Response(response: 200, description: 'OK')] // Response詳細 必須
  public function index()
  {
    //
  }
}