[Tools]ドキュメントから例外処理のプログラムソースを作成するツールを公開

公開先GitHub

Dark Mode

doc-to-exceptions (this link opens in a new window) by ShinyaTomozumi (this link opens in a new window)

Tool to create exception handling source code from documentation.

1 Subscriber 0 Watchers 0 Forks Check out this repository on GitHub.com (this link opens in a new window)

ツール概要

Webサービスを実装する際に、問題がある場合に例外処理を実装します。
例えば必須パラメータが設定されていない場合やデータが存在しない場合などがあります。
その場合に即座にエラーとして返却する必要がありますが、例外処理のソースコードは一つのフォルダもしくはパッケージにまとめておきます。
ただそれを作成するには、コピペで行うよりと書き直しに時間がかかったりファイル名とクラス名が一致しなくて混乱することもあります。
そこでドキュメントに、例外IDを元にパラメータを記述して管理し、それからソースコードを作成するツールを作成しました。

開発環境

本ツールは以下のプログラムで作成しております。

• Python 3.9

また「yaml」ファイルを読み込むために、以下のライブラリをインストールする必要があります。

$ pip install pyyaml

使い方

まずは上記のGitHubからソースコードをクローンします。
ソースコード内に「example.yaml」があるので、それをコピーして記述を修正します。
このツールで使用する「yaml」のフォーマットは以下の通りです。

「yaml」の仕様

## example
version: '1.0' # ドキュメントのバージョンです。
copyright: Sample # コピーライト。
author: AuthorName # 製作者名を設定します。
description: | # この例外処理の説明です。
  Description
type: api # ソースのタイプです。WebAPIであれば「api」と記述します。
exceptions: # ここから以下に例外処理を記述します。
  unknown: # 例外処理のIDを記述します。スネーク形式。
    result: err_unknown # エラーのリザルトコードの文字列です。
    code: -1  # エラーのリザルトコードの数値です。クライアント側でこの数値を元に処理などを行います。
    message: |  # エラーメッセージです。クライアント側で処理をしない場合、このメッセージを表示させます。
      Unknown error.
    response_code: 400  # WebAPIの場合、レスポンスコードを返却します。
    description: |  # この例外処理の説明。どのケースで使用するか等を記載します。
       Exception errors when they occur.

「exeptions」以下から例外情報を追加していきます。

実行コマンド

「yaml」側の設定が完了して以下のコマンドでプログラムを実行します。

python doc_to_exeptions -i [読み込むyamlのパス] -project [使用するプロジェクト名] -o [出力するフォルダ名]

オプションは以下のようになります。

書き出されたファイルをプロジェクトに追加します。（今回のケースはLaravelです)

使用する場合も以下のようにコードを記述する事で例外処理がすぐに実行できます。

「Laravel」のみ対応しておりますが、必要に応じて対応するフレームワークを追加する可能性はあります。
Webサービスの開発にお役に立てれば幸いです。