本日は、日常の開発に使用するツールであるSwaggerをご紹介します。SwaggerはRESTfulなドキュメント生成ツールです。
公式の説明は 「The Best APIs are Built with Swagger Tools」
非常に威圧的です。
Swaggerは、複数の言語フレームワークで使用できます。たとえば、Pythonのflaskフレームワークには「flask-restful-swagger」、Djangoフレームワークは「django-rest-swagger」があり、tornadoも使用できますが、使用量は前の2つよりはるかに少なくなります。
swaggerは強力であり、統合されたツールが非常に多いため、今日では主にswagger-uiを理解しています。
swagger-uiを使用する理由
プログラミングの世界では、プログラマーが最も嫌う2つのことをよく言います。
1.メモや文書を書く2.他の人はメモや文書を書かない。
なぜそう言うのですか?ドキュメントの注釈を管理するのは面倒であるため、APIの更新が頻繁に発生し、ドキュメントはまだ古く、さまざまな同期の不整合が発生します。それは多くの問題を引き起こし、お互いの時間を遅らせるので、誰もがドキュメントのコメントを書くのが好きではありません。
swaggerを使用する主な理由は、フロントエンドとバックエンドの開発ドキュメントの同期の問題を軽減できることです。Swaggerは、コードコメントからAPIドキュメントを自動的に生成して、フロントエンドのドッキングを容易にします。
次に、すべてのインターフェイスのリストを表示できます。これは、フロントエンドとバックエンドでインターフェイスのデバッグを実行するのに非常に便利です。フロントエンドの学生ドッキングインターフェイスはページ上で直接操作でき、郵便配達員やPAWなどのネットワークツールを切り替える必要がありません。これは非常にシンプルで便利です。
以下に、公式のプレビューデータテーブルの定義を示します。
Djangoswaggerのインストールと使用
次に、インストールと使用のプロセスについて説明します。私たちは主にPythonベースなので、swagger-uiを紹介します。ここでは、Djangoの使用法を簡単に紹介します。
pip install django-rest-
swagger受信:Django 1.8+ DjangoRESTフレームワーク3.5.1 + Python 2.7、3.5、3.6
に INSTALLED_APPS
INSTALLED_APPS =( ... 'rest_framework_swagger'、 )
ドキュメントアドレスを追加します。
from django.conf.urls import urlfrom rest_framework_swagger.views import get_swagger_view schema_view = get_swagger_view(title = 'Pastebin API') test_urlpatterns = [ url(r '^ $'、schema_view)#ここでドキュメントディレクトリをカスタマイズします]#ここで必要ですローカル環境またはテスト環境で使用されることに注意してください。オンラインでは使用できません。最も簡単な方法は、前述の方法で、環境変数を使用して現在の環境を判断し、このtest_urlpatternsを追加することです。current_envが['product'、 'staging']にない場合: url_patterns = url_patterns + test_urlpatterns
最終結果は同様の効果です:
Django-filterを使用すると、ほぼXXX管理ページに手を上げるまでの間に、フロントエンドのスクリーニングテストを実行する方が便利です。SwaggerとDjango-REST-Frameworkは、バックエンドの書き込みの追加、削除、変更(CRUD)およびドッキングの完了の速度を大幅に向上させると言えます。
他の言語で使用する
SwaggerはPythonで使用されるだけでなく、他の言語フレームワークでも使用できます。Pythonプログラマーであるかどうかに関係なく、すべての人に使用することをお勧めします。
他の言語ツール統合のアドレス:https://swagger.io/tools/open-source/open-source-integrations/
会社がいくつあるかわかりません。APIが更新されるたびにドキュメントが更新されないため、ドッキングに不整合が生じます。とにかく、周りの友達からフィードバックを聞いています。
あなたの会社がこのような状況にあることに気づいたら、すぐに振り回してください。
上記はswagger-uiの紹介です。実際のswaggerツールには、swagger-editorとswagger-codegenの2つの強力なツールがあります。興味があれば、自分で調べることができます。