この一連のブログ記事では、Swaggerに深く入り込み、そのすべてを理解し、APIを次のレベルに引き上げるためにどのように活用できるかを説明します。各記事では、これらの側面の1つを取り上げます。
問題について話しましょう。私たちはドキュメント化したいAPIを持っています。具体的には、REST APIです（「REST」がここで何を意味するのかは後で説明します）。
その情報を記載したドキュメントやHTMLウェブサイトを管理したり、コードからツールで生成したりすることもできます。このアプローチの欠点は、手動で（または半自動プロセスで）維持する必要があることと、人間が読めるものの、機械が読めるわけではないことです。
別の方法として、いくつかのツールで生成できるWADLを使用する方法があります。この場合、機械が読めますが、人間が読めるものではありません。また、WADLを手動で作成するのは面倒なプロセスです。
両方にとってよりシンプルな解決策を求めた結果、Swaggerが誕生しました。Swaggerは、REST APIを記述する形式のためのルールセット（つまり、仕様）です。この形式は、機械が読めるだけでなく、人間が読めるものでもあります。その結果、プロダクトマネージャー、テスター、開発者の間でドキュメントを共有するために使用できるだけでなく、さまざまなツールによってAPI関連プロセスを自動化するためにも使用できます。
RESTと言うとき、必ずしもRESTfulなルールに従っているわけではありません。REST APIの背後にある基本的な概念を指します。WADLは複雑さを犠牲にしてほぼすべての可能なAPI設計をカバーしますが、Swaggerはより一般的な設計パターンをカバーすることを目的としながら、より簡単に記述して使用できるようにしています。
最新のイテレーションであるSwagger 2.0では、JSONとYAMLの両方で形式を受け入れられるようにし、編集をさらに容易にしました。
Swaggerがどのようなものか理解するために、以下の例を見てください。
swagger: "2.0"
info
version: "1.0"
title: "Hello World API"
paths
/hello/{user}
get
description: Returns a greeting to the user!
parameters
- name: user
in: path
type: string
required: true
description: The name of the user to greet.
responses
200:
description: Returns the greeting.
schema
type: string
400:
description: 「user」に無効な文字が指定されました。
上記の例では、シンプルな「Hello World API」を記述しています。公開されているURLは「/hello/{user}」の1つです。「user」はAPIへの唯一のパラメータで、パスの一部として定義され、文字列であると指定しています。成功応答も記述し、それも文字列であると述べています。「user」に無効な文字が含まれている場合、一般的な400エラーが返される可能性があります。操作全体を通して、追加のドキュメントが提供されていることも確認できます。
これでほぼすべてです。これがSwaggerの概要です。Swagger仕様はhttps://swagger.dokyumento.jp/specificationで誰でも読むことができ、またはこのSwaggerチュートリアルを読むことができます。これには、パス、パラメータ、応答、モデル、セキュリティなどを定義する方法に関する情報が含まれています。Swagger仕様自体はオープンソースであり、ASL 2.0の下で利用できます。
今後のブログ記事では、プロジェクトでSwaggerを使い始める方法、それが一般的なAPIライフサイクルにどのように適合するか、および利用可能なツール（オープンソースと商用）について説明します。
このシリーズで取り上げてほしい「Swagger入門」の特定の側面がある場合は、お気軽にお問い合わせください。できる限り情報を提供できるよう努めます。