YAMLとは、その書き方をわかりやすく解説

Webアプリケーションを作成する際には、YMALがよく利用されているので、Webアプリ開発には必須なスキルだとも言えます。そこで、YAMLを詳しく理解すれば、アプリの開発効率の向上にもつながると思います。本文では、YAMLとは何かを完全に解説した上、YAMLファイルの書き方をも皆さんにわかりやすく解説していきたいと思います。

💡

Apidogは、YAMLフォーマットを完璧に互換できるAPI管理ツールとして、YAMLファイルからAPI仕様をインポートしたり、既存のAPIリクエスト情報やAPI仕様情報に基づいてYAMLファイルを生成したりすることもできます。
また、ApidogのGUIでYAMLを記述しなくても簡単にAPIを設計することもできますし、YAML定義から綺麗なAPI仕様書を生成することもできますので、下記のボタンからApidogを完全無料で利用し始めましょう。👇👇👇

button

YAMLとは

YAMLとは、YAML Ain't Markup Languagの略語として再帰的頭字語を意味して、データをシリアライズするためのテキストベースのマークアップ言語です。

YAMLは何に使う？

YAML (YAML Ain't Markup Language) はデータ序列化のための人間が読み書きしやすいデータシリアライゼーション形式です。主に以下のような目的で利用されます。

設定ファイルの記述形式として：多くのプログラミング言語やフレームワークで設定ファイルのフォーマットとしてYAMLが採用されている。
アプリケーション間でのデータ交換フォーマットとして：JSONと並んでよく利用される。
構造化データの記述に：文書、商品情報、各種メタデータなどを記述するのに利用される。

プログラミング言語からのデータ構造のシリアライズ/デシリアライズ、コンテナオーケストレーションツールのマニフェストファイル記述、各種設定ファイルの記述など、様々な場面で YAML は活用されている重要なデータシリアライゼーションフォーマットです。いずれにせよ、YAMLはAPIドキュメントの標準化フォーマットになりますので、APIドキュメントの記述に使うのは、YAMLの最も主要の利用シーンになると思いますね。

YAMLの特徴

YAMLは、人間が読み書きしやすい記述言語として、主に次のような特徴があります。シンプルで人間に優しい記法が特徴的ですので、設定ファイルの定義などによく利用されています。YAMLの主な特徴といえば、以下のものがあると考えられています：

人間が読み書きしやすい形式でデータを記述できる
JSONなどと比べて記述が簡潔
空白文字(スペース、タブなど)に意味があるのでインデントに注意
コメントを書くことができる
データ型(文字列、数値、配列、オブジェクトなど)を表現できる

YAMLは上記の特徴があるので、YAMLを使って何かを記述したい場合でも、非常に書きやすくなっていると思います。次は、YAMLファイルの書き方をも皆さんに紹介するので、YAMLの書き方にまだ詳しくなっていない方は、次の内容を読み続けて下さい。

YAMLの書き方を解説

YAMLでは基本的にキーと値のペアでデータを表現します。複数のキーと値のペアはインデントで区切って記述できます。YAMLの基本的な書き方は以下のようになります。

キーと値のペアの利用

YAMLでは基本的にキーと値のペアでデータを表現して、キーと値のペアを:で区切って記述しています。

key: value

データ階層の書き方

データの階層が存在している場合は、常にインデント(通常はスペース2つ)を使って、下のオブジェクトを引き続き記述しています。

parent:
  child: value

リストと項目の書き方

配列は-をつかて、アイテムを記述します。複数のアイテムがある場合は、各アイテムの前に、-を使って記述する必要があります。

fruits:
  - apple
  - orange
  - banana

オブジェクトの書き方

オブジェクトの記述もキーと値のペアを利用していますが、インデントして記述する必要があります。

user:
  name: Taro
  age: 23

コメントの書き方

YAMLでコメントを書きたい場合は、#を使用する必要があります。コメントは#から行末までの部分になります。

# これはコメントです

# 値の横にコメントを書くこともできます
key: value  # コメント

# コメントは複数行に渡ることもできます
long_commented_key: |
  この値はコメントの
  後に続きます。

# JSONのようにネストされた構造にもコメントを書けます
parent:
  # 子要素のコメント
  child_key: child_value

# リストの中でもコメントが使えます
shopping_list:
  - milk  # 2リットル
  - eggs  # 10個
  - bread

コメントの規則は以下の通りです:

#から行末までがコメントとして扱われます
コメントは値の前または後に置くことができます
スカラー値の上下にコメントを書くこともできます
コメントは複数行に渡ることができます

YAMLではコメントを自由に書くことでデータの意味や目的を明確にでき、可読性が高まります。設定ファイルやドキュメント化などに役立ちます。

複数行の文字列の書き方

YAMLファイルで複数行の文字列を書く場合は、それを | で囲むする必要があります。例えば：

text: |
  XXXX
  YYYY

以上は、YAMLで何かを記述する際、主な書き方になります。上記のルールを守ると、YAMLフォーマットで簡単に内容を記述することができると思います。JSONデータに比べると、主な違いは、インデントと空白文字が意味を持つことになるので、JSONフォーマットに詳しい方は、YAMLで記述する際、特にこの違いに注意を払う必要があると思います。

YAMLファイルのサンプル

それでは、次は完全なYAMLファイルのサンプルを皆さんに紹介します。このサンプルに基づいて、YAMLファイルの書き方をより深く理解できるよう解説していきたいと思います。

# サンプル YAMLファイル

# 辞書(マップ)
book:
  title: Introduction to YAML
  author:
    # 入れ子のマップ
    name: Taro Yamada
    age: 38
  year: 2023
  pages: 120
  chapters:
    # リスト
    - Introduction
    - Basics
    - Advanced Techniques

# リスト
fruits:
  - apple
  - orange
  - banana

# 文字列
description: |
  YAML is a human-friendly data serialization standard.
  It is commonly used for configuration files and in APIs.

# 数値
price: 9.99

# 真偽値
published: true

# NULL値
score: ~

このYAMLファイルは、以下のようなデータ構造を表しています。

1行目からbook: ではじまるブロックは、1つの辞書(マップ)を定義しています。

book がキーで、その値として辞書のデータが来ます。
title、author、year、pages、chapters がキーです。
author の値は入れ子の辞書構造になっています。
chapters の値はリスト構造です。

fruits: から始まるブロックは、リストを定義しています。

fruitsがキーで、リストが値です。
- apple のように - 付きでアイテムが列記されていますので、このリストに3つのアイテムがあります。

description: では文字列を複数行に渡って定義しています。

price: は数値の定義です。

published: は真偽値の定義です。

score: はNULL値を表す~が設定されています。

このように、YAMLでは様々なデータ型を柔軟に定義でき、入れ子構造も簡単に表現できます。

APIの記述：ApidogはYAMLに完璧に対応

Webアプリ開発中に、APIの仕様記述、ドキュメント、構成定義など、APIとの関連でYAMLは欠かせない存在ともなっています。OpenAPI・Swaggerデフォルトの仕様フォーマットはYAMLになるので、API領域ではYAMLは非常に汎用されているフォーマットになります。Yamlで記述しているAPIなら、Apidogはそれに完璧に対応できます。

button

ApidogはYAMLフォーマットのOpenAPI 3、Swagger 1、2、3のAPIをインポートすることをサポートしているので、YAMLフォーマットのAPIを完全に解析して、APIのデータを完全にApidogにインポートしてテストできます。

ステップ⒈プロジェクトの設定を開き、「データをインポート」をクリックすると、「OpenAPI/Swagger」を選択して、YAMLファイルをApidogにドラッグします。

ステップ⒉ここでYAMLファイルが解析され、データの保存先を選択すると、「確認」ボタンをクリックするだけで、それを簡単にApidogにインポートできます。

そして、ApidogというAPI管理ツールを使って、当該APIをテストしたりすることができるようになりますし、APIリクエストを送信して直ちに内蔵のモックサーバーを使って仮のレスポンスデータを取得することもできます。

button

まとめ

YAMLは人間が読み書きしやすいデータ構造化の形式で、Webアプリケーション開発では設定ファイルの記述やAPIドキュメントの作成など、幅広い場面で利用されています。YAMLの構文は比較的シンプルですが、インデントやコメントの扱いなど独自の規則があるので、その点に注意が必要です。YAMLを適切に活用することで、開発の効率化やドキュメントの品質向上が期待できます。

本記事でYAMLの基本的な書き方を理解し、実際の開発でYAMLを活用できるようになることを目指しましょう。