菅原20240605

1.　概要

新規作成の場合　　※バージョンアップ（v1.0→v1.1）も含む
1. API仕様をYAML形式で作成する
2. Zendeskで空の記事を作成する
3. 作成したYAMLファイルをGitHubにpushする
4. 設定ファイル「articles_mapping.json」に追記してGitHubにpushする
5. 【自動】GitHubから、2で作成したZendeskの記事にコピー（AWS CodePipeline）
6. 【自動】Zendeskから、リファレンスサイトのDBにコピー
7. リファレンスサイト上に、新規追加した記事が反映される

更新の場合
1. 既存のAPI仕様を更新する
2. 更新したYAMLファイルをGitHubにpushする
3. 【自動】GitHubから、2で作成したZendeskの記事にコピー（AWS CodePipeline）
4. 【自動】Zendeskから、リファレンスサイトのDBにコピー
5. リファレンスサイト上に、新規追加した記事が反映される

2.　新規作成手順

API仕様をYAML形式で作成する
- 下記に留意して任意のエディタで API リファレンスを作成する
  - utf-8 であること
  - ファイル名に日本語などマルチバイト文字を使用しないこと
Zendeskで空の記事を作成する
- メニューから「Zendesk」をクリックする
- 画面右上四角 > Guide(ヘルプセンター)
- 画面左上の「追加」> 記事
- 記事編集画面で、タイトルを編集する
  - タイトルはリファレンスサイトの左のメニューバーで表示される
- 記事編集画面で、右の「記事の設定」を変更する
  - 管理人：Administrators
  - 表示対象ユーザ：いずれかを選択
    - サインインユーザ（一般ユーザにも公開したい場合）
    - エージェントと管理者（MSPF関係者のみに公開したい場合）
  - 次のセクションで公開
    - リファレンスサイトで表示させたいセクションを選択
    - チェックボックスはデフォルト設定のままでOK
  - ラベル：
    - ラベル設定方法の「各記事ごとのページで行う方法」を参照
  - その他の項目は設定不要
- 記事編集画面で、右上のボタンより公開する
- 記事編集画面で、左下の表示ボタンを押し、Zendesk ヘルプセンターで当該記事を表示する
- Zendesk ヘルプセンターで表示した当該記事のアドレスバーから、記事 ID を取得する
  - 下記の例では記事ID：24726460055705
  - 記事編集画面のbrand_id：12397645952921ではないので注意
作成したYAMLファイルをGitHubにpushする
- API-Reference-MD-Contents（trpブランチ）
- 作成した YAML ファイルを /yaml ディレクトリ配下に追加する
  - 拡張子は.yaml　※.ymlはNG
  - 追加パスは Zendesk で記事を配置したカテゴリ、セクションが分かる様に任意に設定
設定ファイル「articles_mapping.json」に追記してGitHubにpushする
- このファイルで、Zendeskの記事IDとyamlファイルをマッピングしているため追加が必要
- 下記セットを追記する
  - id：上で取得した記事 ID
  - path：YAML ファイルパス
    - /yaml ディレクトリより下のパス
    - 拡張子はあってもなくても良い
【自動】【2-3分】GitHubから、Zendeskの空の記事にコピー（AWS CodePipeline）
【自動】【?分】Zendeskから、リファレンスサイトのDBにコピー
リファレンスサイト上に、新規追加した記事が反映される
- 10分以上経っても記事が反映されない場合は、リファレンスサイト開発メンバーにお問い合わせください