Jira APIを使用する際、
チケットの説明文に、単純なテキスト以外にもリスト形式やコードブロックを使用すれば、よりわかりやすく記述が可能です。
こちらでチケットの作成コードを紹介しているので組み合わせて活用しましょう！
リッチテキストとは
リッチテキストとは、文字装飾や構造的な要素を用いて、単純なプレーンテキスト（無装飾の文字列）よりも視覚的に情報をわかりやすく伝えることを目的としたフォーマットです
Jira リッチテキスト仕様のtype一覧
Jira のリッチテキストは、JSON データ形式で記述されます。この形式を利用して、Jira APIのdescriptionフィールドに構造的なデータを追加できます。
| type | 説明 | オプション |
|---|---|---|
| text | テキストの装飾やリンク | 装飾（太字、斜体など）が可能。 |
| paragraph | 一般的な説明文や文章 | 通常のテキストを含むブロック要素。 |
| heading | セクションの見出し |
attrs.levelで階層（1～6）を指定可能。 |
| listItem | リスト内の各項目 |
bulletListやorderedList内で使用。 |
| bulletList | 箇条書きリスト | 順序なしリスト |
| orderedList | 番号付きリスト | 順序付きリスト（番号付き） |
| codeBlock | コードスニペット | コードを記述する。 |
| blockquote | 引用 | 引用文や注釈を記述する。 |
| expand | 展開 | 折りたたみ可能なセクション。 |
| rule | 水平線（区切り線） | 内容を分割するための区切りを挿入する。 |
| media | 画像やファイル | Jiraにアップロードされたメディア（画像やファイル）。 |
| panel | 強調表示用のパネル | 種類（情報、成功、エラーなど）を指定。 |
| hardBreak | 改行 | 明示的に改行を挿入する。 |
1. text
概要
段落や他の構造内で使用する基本的なテキスト要素。
構造例
{
"type": "text",
"text": "ノーマルテキスト",
"marks": [
{ "type": "strong" },
{ "type": "em" }
]
}
用途
- 他のタイプ（paragraph, heading など）内で使用される基本テキスト。
マークアップ（太字、斜体など）を適用可能。
2. paragraph
概要
通常の段落を表現します。
構造例
{
"type": "paragraph",
"content": [
{ "type": "text", "text": "段落のテキスト." }
]
}
用途
- 一般的なテキストコンテンツ。
- タスクや説明文などに使用。
3. heading
概要
見出しを表現します。
構造例
{
"type": "heading",
"attrs": { "level": 1 },
"content": [
{ "type": "text", "text": "見出しのテキスト" }
]
}
用途
- 内容をセクション化する際の見出し。
attrs.level で階層（1～6）を指定、h1 ~ h6のことですね。
5. bulletList
概要
順序なしリストを表現します。
構造例
{
"type": "bulletList",
"content": [
{ "type": "listItem", "content": [{ "type": "paragraph", "content": [{ "type": "text", "text": "箇条書き1" }] }] },
{ "type": "listItem", "content": [{ "type": "paragraph", "content": [{ "type": "text", "text": "箇条書き2" }] }] }
]
}
用途
- 順序なしリスト（点やハイフン）で項目を表示。
6. orderedList
概要
順序付きリストを表現します。
構造例
{
"type": "orderedList",
"attrs": { "order": 1 },
"content": [
{ "type": "listItem", "content": [{ "type": "paragraph", "content": [{ "type": "text", "text": "番号付きリスト1" }] }] },
{ "type": "listItem", "content": [{ "type": "paragraph", "content": [{ "type": "text", "text": "番号付きリスト2" }] }] }
]
}
用途
- 順序付きリスト（番号付き）で項目を表示。
7. codeBlock
概要
コードスニペットを表現します。
構造例
{
"type": "codeBlock",
"attrs": { "language": "javascript" },
"content": [
{ "type": "text", "text": "console.log('Hello, world!');" }
]
}
用途
- プログラムコードやスニペットを表示。
8. blockquote
概要
引用ブロックを表現します。
構造例
{
"type": "blockquote",
"content": [
{ "type": "paragraph", "content": [{ "type": "text", "text": "引用のテキスト。" }] }
]
}
用途
- 引用や注釈を表現。
9. expand
概要
展開可能なセクションを表現します。
構造例
{
"type": "expand",
"attrs": { "title": "詳細" },
"content": [
{ "type": "paragraph", "content": [{ "type": "text", "text": "ここに詳細情報が表示されます。" }] }
]
}
用途
- 折りたたみ可能な詳細情報を提供。
10. rule
概要
水平線（ルール）を表現します。
構造例
{
"type": "rule"
}
用途
- 内容を分割するための水平線。
11. media
概要
メディア（画像やファイル）を埋め込みます。
ローカルからアップロードが出来ず、既にjiraにアップロードした画像からIDを取得する形で記載するそうです。ちょっと使い勝手が悪いですかね。
構造例
{
"type": "media",
"attrs": {
"type": "file",
"id": "file-id",
"collection": "media-collection"
}
}
用途
- 画像やファイルを表示。
12. panel
概要
色付きの枠（パネル）で情報を強調します。
構造例
{
"type": "panel",
"attrs": { "panelType": "info" },
"content": [
{ "type": "paragraph", "content": [{ "type": "text", "text": "情報パネルのテキスト" }] }
]
}
用途
- 情報、注意、エラーなどを強調。
- panelTypeをinfo, success, warning, note, errorで指定できる。
13. hardBreak
概要
改行を表現します。
構造例
{
"type": "paragraph",
"content": [
{ "type": "text", "text": "これは改行が含まれるテキストです。" },
{ "type": "hardBreak" },
{ "type": "text", "text": "改行後のテキスト。" }
]
}
用途
- 文中で明示的な改行を挿入。
まとめ
これらのタイプを組み合わせることで、Jira API のリッチテキストを活用して、説明文やコメントに豊富な表現を追加できます。例えば、paragraph、codeBlock、expand を組み合わせて、以下のような説明文を構築できます。
{
"type": "doc",
"version": 1,
"content": [
{
"type": "paragraph",
"content": [{ "type": "text", "text": "Main description here." }]
},
{
"type": "expand",
"attrs": { "title": "Details" },
"content": [
{ "type": "paragraph", "content": [{ "type": "text", "text": "Hidden details here." }] }
]
},
{
"type": "codeBlock",
"attrs": { "language": "ruby" },
"content": [
{ "type": "text", "text": "def example_method\n puts 'Hello, World!'\nend" }
]
}
]
}
これを使えば、Jira のリッチテキストで柔軟な表現が可能です！