内容
- REST API開発の効率化のため、ツールを使って仕様書生成、コード生成、スタイルチェック、自動フォーマットをすると思います。
- Pythonを対象に、私が便利だと思っているツールをまとめます。
- 開発エディターは、VSCodeです。
REST API関連
- OpenAPI仕様をyaml形式で書いて、REST APIのインターフェース仕様書生成とコード生成をします。
- インターフェース仕様書
- サーバー側のスタブ（コントローラー、HTTPリクエスト・レスポンスのモデル）
- フロント側のREST API用のクライアントSDK
- サーバースタブの生成は非常に便利です。
- PythonでFlaskのコードを生成すると、OpenAPI仕様をベースにHTTPリクエストの制御をするFlaskアプリ（connexionというライブラリでラップされている）のコントローラーまでできます。
- OpenAPI仕様を基に、HTTPリクエストのバリデーションをしてくれるので、自分でバリデーションのコードを開発する必要がありません。
- また、クライアント側に対しては、サーバー側が完成するまでのスタブサーバーとして利用することもできます。
- クライアントSDKも便利です。自分でエンドポイントやリクエストを作っていくより簡単です。
- 使用するツールは下記です。
| 用途 | ツール名 | 説明 | リンク |
|---|---|---|---|
| OpenAPI仕様の編集 | VSCode + OpenAPI Editor(拡張機能) | VSCode上で、OpenAPI仕様を書きます。左サイドに、パスやスキーマの目次ができるのが便利です。 | https://marketplace.visualstudio.com/items?itemName=42Crunch.vscode-openapi |
| OpenAPI仕様の参照 | VSCode + Swagger Viewer(拡張機能) | OpenAPI仕様をドキュメントとして参照することができます。 | https://marketplace.visualstudio.com/items?itemName=Arjun.swagger-viewer |
| OpenAPI仕様のバリデーション | openapi-generator | CLIでOpenAPI仕様のバリデーションができます。 OpenAPI Editorでは検出しきれないエラーも検出できます。ただ、これでも検出しきれないバグはあります。例えば、スキーマでrequiredに設定した項目が、実はプロパティ定義されていないとか。こういったものは、サーバースタブをコード生成して、起動してみるとエラーするので気づきます。 |
https://github.com/OpenAPITools/openapi-generator |
| コード生成 | openapi-generator | OpenAPI仕様（yamlファイル）からコード生成（サーバースタブ、クライアントSDK）できます。 | 同上 |
| ドキュメント生成 | openapi-genrator | REST APIインターフェース仕様書をHTML形式で生成します。 | 同上 |
Python関連
- 開発したコードから、クラス図、クラス仕様書を生成します。
- クラス仕様書を生成する前提として、docstringを書く必要があります。
- コード開発では、Linter（スタイルチェック）とFormatter（自動フォーマット）も便利です。
- 使用するツールは下記です。
| 用途 | ツール名 | 説明 | リンク |
|---|---|---|---|
| クラス図の生成 | Pyreverse | クラス図生成 | https://pypi.org/project/pylint/ |
| クラス仕様書の生成 | Sphinx | クラス仕様書生成 |
https://www.sphinx-doc.org/ja/master/ Sphinxインストール手順 |
| docstringの記載補助 | VSCode + Python Docstring Generator | コードからdocstringの雛形を生成することができます。例えば、メソッドの場合は、サマリー行、引数の名前、型、戻り値の型がコードから生成されるので、自分では説明を書くだけでOKです。 | https://marketplace.visualstudio.com/items?itemName=njpwerner.autodocstring |
| Pythonのスタイルチェック | VSCode + flake8 | pep8に準拠しているかチェックして結果表示してくれます。 | https://pypi.org/project/flake8/ |
| Pythonの自動フォーマット | VSCode + autopep8 | ある程度、自動でpep8に準拠するようにコードを自動修正してくれます。例えば、クラス定義の上に2行空白行を開けるとか、引数に半角スペースを入れるとか。 | https://pypi.org/project/autopep8/ |
DB関連
- コード開発では多くのケースでDBを利用します。
- GUIで、ER図、テーブル定義、DDL生成ができる便利なツールがあるので紹介します。
- EclipseのプラグインのERMasterです。
- ER図をGUIで書けば、そこからExcelのテーブル仕様書、DDL文を生成することができます。
- 概念データモデルはパワポやdraw.ioで書いて、論理データモデルからERMasterで書くと良いと思います。
| 用途 | ツール名 | 説明 | リンク |
|---|---|---|---|
| ER図、テーブル定義、DDL生成 | ERMaster | Eclipseのプラグインで、GUIで、ER図、テーブル定義、DDL生成ができます。 | http://ermaster.sourceforge.net/index_ja.html |