Go to Qiita Advent Calendar 2024 Top
LoginSignup
15
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@kamome_susume(Lara)in株式会社 CIN GROUP (ITS事業部)

【脱エクセル】Swaggerを使ってAPI設計書を書く

Posted at

「エクセルでAPI設計書を書くのは卒業したい…」

「Swaggerを使ってAPI設計書を作成したいな….」

この記事では上記の悩みを解決します。

Swaggerは、いい感じのUIでAPI設計書をかけるものです。

今回は、そんなSwaggerを用いてAPI設計書を作成する方法をみなさんにお伝えしていきます。

エクセルでAPI設計書を書くのはもうやめだ！！って人はぜひこの記事を参考にしてみてくださいね。

Swaggerって？

Swaggerは、OpenAPI仕様で作成されたオープンソースツール。REST APIの設計や構築、ドキュメント作成に役立ちます。

利用可能なエンドポイントやパラメータ、レスポンス、エラーハンドリングなど記載することができます。

実際に見た方が早いかと思うので、swaggerで作成したAPIの設計書になります↓

image

image

image

image

Swaggerは、YAML、JSON形式で記述することができ、パス、パラメータなど記載することでAPI設計書を作成していきます。

基本的な書き方は以下です。

Swaggerの基本構文

エクセルとSwaggerの比較

API設計書を書くにあたり、エクセルとSwaggerの比較をしていきたいと思います。

エクセルの場合：

  • シンプルで使いやすい
  • API設計書はエクセルで作成するのが一般的
  • API設計書のフォーマットなどを考えるのが面倒
  • 体裁など(改行や処理の番号降るなど)の作業が発生する
  • かなり細かいところまで自由に記載できる(エクセルの機能が豊富だから)
  • 古びた老人のような感じがする

Swaggerの場合：

  • モダンな感じがする
  • swagger用のファイルのコードをいじる必要はあるが、ドキュメントを自動で生成してくれる
  • 決まったレイアウトでデザインやフォーマットをいちいち考えなくていい
  • 保守性や管理が楽
  • swaggerの構文などに縛られる
  • 構文理解など、慣れるまで時間かかる

エクセルとswaggerを比較した際に、swaggerの利点は「swaggerがいい感じにドキュメントのフォーマットを自動で生成してくれる」「保守性がエクセルに比べて楽」だと感じます。

Swaggerの書き方をざっくり解説

それでは実際にSwaggerを触っていきます。

まずは、vscodeを利用している場合は、以下の拡張機能を入れた方がいいです。

SwaggerのUI拡張機能

VScodeの拡張機能よりSwagger Viewerをインストールする

インストールができたら、以下の操作でswaggerのUIを開けます。

①コマンドパレットを開く

macの場合：shift+command+P

windowsの場合： Shift+Alt+P

②コマンドパレットからPreview Swaggerを選択する

Swaggerの書き方に関して

ユーザー情報のAPI設計の書き方を通してswaggerの書き方を見ていきます。

要点はこんな感じです。

  • パスの書き方
  • パラメータの書き方
  • 正常、異常系の書き方
  • レスポンスの書き方
  • タグの設定

今回解説するコードは以下になります。(YAML形式)

openapi: '3.0.2'
info:
  title: skillcode API設計書
  version: '1.0'
servers:
  - url: http://localhost:8000
    description: ローカル環境

tags:
  - name: "users"
    description: "ユーザー関連"

paths:
  /users/{user_id}:
    get:
      summary: ユーザー情報取得API
      description: 個別ユーザーの情報を取得する
      tags: ["users"]
      parameters:
        - name: user_id
          in: path
          required: true
          description: ユーザーID
          schema:
            type: integer
            format: int64
            minimum: 1
            example: 1
      responses:
        200:
          description: 成功時のユーザー情報レスポンス
          content:
            application/json:
              schema:
                type: object
                properties:
                  user_id:
                    type: integer
                    description: ユーザーID
                    format: int64
                    minimum: 1
                    example: 1
                  user_name:
                    type: string
                    description: ユーザー名
                    maxLength: 50
                    example: 山田太郎
                  email:
                    type: string
                    description: メールアドレス
                    maxLength: 255
                    example: yamada@google.com
                  self_introduction:
                    type: string
                    description: 自己紹介
                    nullable: true
                    format: longText
                    example: 自己紹介文
        404:
         description: ユーザー情報が0件
        default:
          description: 想定外エラー

パスに関して

image

書き方は、以下になります。(直感的に書けますね)

paths:
  /users/{user_id}:
    get:
      summary: ユーザー情報取得API
      description: 個別ユーザーの情報を取得する

pathsにエンドポイントとHTTPメソッドを指定できます。

summaryはAPI名、descriptionにはAPIの説明とか書けばOKです。

tagsに関しては、後ほど解説します。

パラメータに関して

image

書き方は、以下になります。

  parameters:
    - name: user_id
      in: path
      required: true
      description: ユーザーID
      schema:
        type: integer
        format: int64
        minimum: 1
        example: 1

parametersには、パラメータを記載していきます。

パラメータ名を書く場合は、-name: パラメータ名…のように記述すればOKです。

-inはパラメータの場所を表しています。query, header, path, formDataなどがあります。

requiredは必須か、NULL許可かを表しています。

schemaには、型やサンプル値などを記載することが可能です。

詳細は、以下を確認してください。

Swaggerのschema

正常系・異常系に関して

image

書き方は以下になります。

      responses:
        200:

  …

        404:
         description: ユーザー情報が0件
        default:
          description: 想定外エラー

正常系や異常系は上記のように、responsesの部分に記載していく形になります。

独自にエラーレスポンスを返す場合でも、以下のように書いていけばOKです。

400:

description:  エラーメッセージ

レスポンスに関して

image

JSON形式でレスポンスを返す場合は以下のようなサンプルコードを書けばOKです。

      content:
        application/json:
          schema:
            type: object
            properties:
              user_id:
                type: integer
                description: ユーザーID
                format: int64
                minimum: 1
                example: 1

schemaで使われるデータ型に関しては、

  • string
  • number
  • integer
  • boolean
  • array
  • object

などがあります。

また、formatに関しては、

  • int32(符号付き32ビット)
  • int64(符号付き64ビット)
  • float(浮動小数)
  • double(倍精度浮動小数)
  • password
  • date
  • date-time
  • uuid

などがあります。

swaggerのtype

タグの設定に関して

最後にタグについて解説して終わります。
image

タグを設定することでAPIをまとめられます。

usersというタグでAPIをまとめてみましょう。

今回は、もともとあるGETリクエストのAPIにPOSTを足しました。

追加した内容は、/usersから始まるコードからになります。

tags:
  - name: "users"
    description: "ユーザー関連"

paths:
  /users/{user_id}:
    get:
      summary: ユーザー情報取得API
      description: 個別ユーザーの情報を取得する
      tags: ["users"]
      parameters:
        - name: user_id
          in: path
          required: true
          description: ユーザーID
          schema:
            type: integer
            format: int64
            minimum: 1
            example: 1
      responses:
        200:
          description: 成功時のユーザー情報レスポンス
          content:
            application/json:
              schema:
                type: object
                properties:
                  user_id:
                    type: integer
                    description: ユーザーID
                    format: int64
                    minimum: 1
                    example: 1
                  user_name:
                    type: string
                    description: ユーザー名
                    maxLength: 50
                    example: 山田太郎
                  email:
                    type: string
                    description: メールアドレス
                    maxLength: 255
                    example: yamada@google.com
                  self_introduction:
                    type: string
                    description: 自己紹介
                    nullable: true
                    format: longText
                    example: 自己紹介文
        404:
         description: ユーザー情報が0件
        default:
          description: 想定外エラー
  /users:
    post:
      summary: ユーザー情報登録API
      description: ユーザー情報を登録するAPI
      tags: ["users"]
      parameters:
        - name: user_name
          in: query
          required: true
          description: ユーザー名
          schema:
            type: string
            example: 山田
      responses:
        200:
          description: 成功時のユーザー情報レスポンス
        404:
         description: ユーザー情報が0件
        default:
          description: 想定外エラー

タグの設定のやり方に関しては、以下のようにまずはタグ名を定義します。

tags:
  - name: "users"
    description: "ユーザー関連"

タグ名を定義したら、HTTPリクエストの部分で呼び出すタグと紐付けるだけです。

  /users/{user_id}:
    get:
      summary: ユーザー情報取得API
      description: 個別ユーザーの情報を取得する
      tags: ["users"]

…….

  /users:
    post:
      summary: ユーザー情報登録API
      description: ユーザー情報を登録するAPI
      tags: ["users"]

このように記載することで、今回の場合だとusersというタグにAPIがまとめられます。

まとめ

今回はswaggerを使って脱エクセルでAPI設計書を作成する方法を説明しました。swaggerを勉強して、モダンなAPI設計書を作成していきましょう。

15
1
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
15
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?