Jira APIでのチケット作成に活かすリッチテキスト(type)一覧

Jira APIを使用する際、
チケットの説明文に、単純なテキスト以外にもリスト形式やコードブロックを使用すれば、よりわかりやすく記述が可能です。

こちらでチケットの作成コードを紹介しているので組み合わせて活用しましょう！

https://qiita.com/joyun/items/7e4555e96699cf8369fe


# リッチテキストとは
リッチテキストとは、文字装飾や構造的な要素を用いて、単純なプレーンテキスト（無装飾の文字列）よりも視覚的に情報をわかりやすく伝えることを目的としたフォーマットです

# 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`

### 概要
段落や他の構造内で使用する基本的なテキスト要素。
![スクリーンショット 2024-11-30 19.55.15.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3634386/40302554-8aea-c94b-694e-c6713698878e.png)


### 構造例
```json
{
  "type": "text",
  "text": "ノーマルテキスト",
  "marks": [
    { "type": "strong" },
    { "type": "em" }
  ]
}
```

### 用途
- 他のタイプ（paragraph, heading など）内で使用される基本テキスト。
マークアップ（太字、斜体など）を適用可能。

## 2. `paragraph`

### 概要
通常の段落を表現します。
![スクリーンショット 2024-11-30 19.22.32.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3634386/ceb7b7a9-d916-7aca-fc73-9e2d33f444da.png)

### 構造例
```json
{
  "type": "paragraph",
  "content": [
    { "type": "text", "text": "段落のテキスト." }
  ]
}
```

### 用途
- 一般的なテキストコンテンツ。
- タスクや説明文などに使用。

## 3. `heading`

### 概要
見出しを表現します。
![スクリーンショット 2024-11-30 19.22.45.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3634386/77d8d099-e258-2f94-566a-dd36e8120a5d.png)

### 構造例
```json
{
  "type": "heading",
  "attrs": { "level": 1 },
  "content": [
    { "type": "text", "text": "見出しのテキスト" }
  ]
}
```

### 用途
- 内容をセクション化する際の見出し。
attrs.level で階層（1～6）を指定、h1 ~ h6のことですね。

## 5. `bulletList`

### 概要
順序なしリストを表現します。
![スクリーンショット 2024-11-30 19.22.51.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3634386/fad8d0c6-bf20-c7ad-19dc-5c094ccffee6.png)


### 構造例
```json
{
  "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`

### 概要
順序付きリストを表現します。
![スクリーンショット 2024-11-30 19.22.57.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3634386/7ab8f08b-72d2-1bbd-5818-5f8e0a50768d.png)

### 構造例
```json
{
  "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`

### 概要
コードスニペットを表現します。
![スクリーンショット 2024-11-30 19.23.04.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3634386/11cd2ddd-5ec1-693e-de11-1a173f58b4b2.png)

### 構造例
```json
{
  "type": "codeBlock",
  "attrs": { "language": "javascript" },
  "content": [
    { "type": "text", "text": "console.log('Hello, world!');" }
  ]
}
```

### 用途
- プログラムコードやスニペットを表示。

## 8. `blockquote`

### 概要
引用ブロックを表現します。
![スクリーンショット 2024-11-30 19.23.23.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3634386/0aacaa06-5c53-1008-0f07-73b009df6977.png)
### 構造例
```json
{
  "type": "blockquote",
  "content": [
    { "type": "paragraph", "content": [{ "type": "text", "text": "引用のテキスト。" }] }
  ]
}
```

### 用途
- 引用や注釈を表現。

## 9. `expand`

### 概要
展開可能なセクションを表現します。
![スクリーンショット 2024-11-30 19.23.30.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3634386/f1093d72-eae5-16b4-a07d-876af3e9e2a7.png)

### 構造例
```json
{
  "type": "expand",
  "attrs": { "title": "詳細" },
  "content": [
    { "type": "paragraph", "content": [{ "type": "text", "text": "ここに詳細情報が表示されます。" }] }
  ]
}
```

### 用途
- 折りたたみ可能な詳細情報を提供。

## 10. `rule`

### 概要
水平線（ルール）を表現します。
![スクリーンショット 2024-11-30 19.23.38.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3634386/0152ae7e-5a9d-53b9-fcba-c62c658dcf8b.png)

### 構造例
```json
{
  "type": "rule"
}
```

### 用途
- 内容を分割するための水平線。

## 11. `media`

### 概要
メディア（画像やファイル）を埋め込みます。
ローカルからアップロードが出来ず、既にjiraにアップロードした画像からIDを取得する形で記載するそうです。ちょっと使い勝手が悪いですかね。
![uploading...0]()


### 構造例
```json
{
  "type": "media",
  "attrs": {
    "type": "file",
    "id": "file-id",
    "collection": "media-collection"
  }
}
```

### 用途
- 画像やファイルを表示。

## 12. `panel`

### 概要
色付きの枠（パネル）で情報を強調します。
![スクリーンショット 2024-11-30 19.33.37.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3634386/a688e672-0a6a-8c9b-8ec8-e7c56a7b63ba.png)

### 構造例
```json
{
  "type": "panel",
  "attrs": { "panelType": "info" },

  "content": [
    { "type": "paragraph", "content": [{ "type": "text", "text": "情報パネルのテキスト" }] }
  ]
}
```

### 用途
- 情報、注意、エラーなどを強調。
- panelTypeをinfo, success, warning, note, errorで指定できる。

## 13. `hardBreak`

### 概要
改行を表現します。
![スクリーンショット 2024-11-30 19.23.53.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3634386/753bee7e-6c67-a374-5115-7c626e4e1225.png)

### 構造例
```json
{
  "type": "paragraph",
  "content": [
    { "type": "text", "text": "これは改行が含まれるテキストです。" },
    { "type": "hardBreak" },
    { "type": "text", "text": "改行後のテキスト。" }
  ]
}
```

### 用途
- 文中で明示的な改行を挿入。

# まとめ
これらのタイプを組み合わせることで、Jira API のリッチテキストを活用して、説明文やコメントに豊富な表現を追加できます。例えば、paragraph、codeBlock、expand を組み合わせて、以下のような説明文を構築できます。

```json
{
  "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 のリッチテキストで柔軟な表現が可能です！