Swagger-RESTful Web APIのスマートドキュメント-初心者向けのジュニアバックエンド開発者レビュー

まえがき

産業用コードを書く分野で最初の一歩を踏み出したチームは、C＃のソフトウェア製品の機能のための便利なAPIを開発しました（便宜上、Eという文字で呼びましょう）。これは長年にわたって存在し、非常にポジティブな側面で市場に定着しました。 そして、ここでは、若いパダワンはまだ質問をするべきではないように見えますが、もちろん、以前に、おそらくあなたがあなた自身のウェブAPIを書いたと想像してください。しかし、それは幅広い読者にとってはありそうにないことです。 APIの機能に興味がある人は、詳細な手順が記載されたpdfファイルを投げたでしょう（少なくとも私はそうしていました）。 「API機能の参照先」-テキストドキュメントへのリンクを取得することを期待して、チームリーダーに尋ねました。 「Swaggerを見てください」と彼は答えました。

待ってください。製品が長い間正常に機能しているのはどのようになっているのでしょうか。そして、あなたは今それだけにAPIを書いていますか？

そうです、最近まで、Eには便利なパブリックAPIがありませんでした。 実際、すべての作業はWebインターフェイスを介して行われ、バックエンドは多くの内部マイクロサービスで構成されていたため、内部ビジネスロジックを明確に理解することなく外部から統合することはできませんでした。 サーバーと直接対話するクライアントに注意を払う必要がありました。つまり、美しく便利なAPIを提供することを意味していました。 これには何が必要ですか？ 少し前に書かれたのは、すべての内部マイクロサービスと連携して作業を確立し、便利で美しいドキュメントを提供して、美しく理解しやすく、最も重要な商業的に成功させることです。

さて、Swaggerとは何ですか？また、Swaggerの世界への有用性は？

基本的に、SwaggerはRESTful API仕様のフレームワークです。 その魅力は、仕様をインタラクティブに表示できるだけでなく、リクエストを送信することもできるという事実にあります-いわゆるSwagger UI、これはどのように見えるかです：







ご覧のように-モデル、応答コード、クエリパラメータを含むメソッドの完全な説明-一般に、明らかに。

そして、それはどのように機能しますか？

ASP.NET CoreでSwaggerを実装するための優れたガイド

この記事の最初からです。



アイデアは、APIメソッドの特別な注釈を使用して表示を構成することです。以下に例を示します。

Swagger codegen

本当にしたい場合は、Swagger API仕様に従ってクライアントまたはサーバーを直接生成できます。そのためには、Swagger-Codegenコードジェネレーターが必要です。 ドキュメントの説明は、説明する必要はないと思います。

これはSwagger Codegenプロジェクトであり、OpenAPI仕様が自動的に与えられると、APIクライアントライブラリの生成（SDK生成）、サーバースタブ、およびドキュメントが可能になります。 現在、次の言語/フレームワークがサポートされています。

• APIクライアント：ActionScript、Ada、Apex、Bash、C＃（.net 2.0、3.5以降）、C ++（cpprest、Qt5、Tizen）、Clojure、Dart、Elixir、Elm、Eiffel、Erlang、Go、Groovy、Haskell（http -client、Servant）、Java（Jersey1.x、Jersey2.x、OkHttp、Retrofit1.x、Retrofit2.x、Feign、RestTemplate、RESTEasy、Vertx、Java用Google APIクライアントライブラリ、Rest-assured）、Kotlin、Lua、 Node.js（ES5、ES6、AngularJS with Google Closure Compilerアノテーション）Objective-C、Perl、PHP、PowerShell、Python、R、Ruby、Rust（rust、rust-server）、Scala（akka、http4s、swagger-async- httpclient）、Swift（2.x、3.x、4.x）、Typescript（Angular1.x、Angular2.x、Fetch、jQuery、Node）
• サーバースタブ：Ada、C＃（ASP.NET Core、NancyFx）、C ++（Pistache、Restbed）、Erlang、Go、Haskell（Servant）、Java（MSF4J、Spring、Undertow、JAX-RS：CDI、CXF、Inflector、RestEasy 、Play Framework、PKMST）、Kotlin、PHP（Lumen、Slim、Silex、Symfony、Zend Expressive）、Python（Flask）、NodeJS、Ruby（Sinatra、Rails5）、Rust（rust-server）、Scala（Finch、Lagom、スカラトラ）
• APIドキュメントジェネレーター：HTML、Confluence Wiki
• 構成ファイル：Apache2
• その他：jmeter

その他の情報、特に使用手順は次のとおりです。

一般的な情報



そしてここ： 詳細

おわりに

これは初心者API開発者向けの簡単な視覚的概要であり、その目的はSwaggerが何であるか、なぜそれが必要なのか、私の個人的な観点からの主な利点を提供することの概要を提供することでした。