<h1 id="%E6%A6%82%E8%A6%81" data-line="0" class="code-line">
<a class="header-anchor-link" href="#%E6%A6%82%E8%A6%81" aria-hidden="true"></a> 概要</h1>
<p data-line="2" class="code-line">この記事は、ユビキタス言語の管理を自動化するGitHub Actionsの紹介記事です。ドキュメントとソースコードを密接に関連付けることで、ユビキタス言語の統一と管理を容易にできます。<br style="display:none">
<span class="embed-block zenn-embedded zenn-embedded-card"><iframe id="zenn-embedded__13ab74930552a" src="https://embed.zenn.studio/card#zenn-embedded__13ab74930552a" data-content="https%3A%2F%2Fgithub.com%2FGlider2355%2Fubi-doc" frameborder="0" scrolling="no" loading="lazy"></iframe></span><a href="https://github.com/Glider2355/ubi-doc" style="display:none" target="_blank" rel="nofollow noopener noreferrer">https://github.com/Glider2355/ubi-doc</a></p>
<p data-line="5" class="code-line">執筆時点では下記の言語に対応しています。</p>
<ul data-line="7" class="code-line">
<li data-line="7" class="code-line">PHP</li>
<li data-line="8" class="code-line">Java</li>
<li data-line="9" class="code-line">Kotlin</li>
<li data-line="10" class="code-line">Ruby</li>
</ul>
<h2 id="%E4%B8%BB%E3%81%AA%E6%A9%9F%E8%83%BD" data-line="12" class="code-line">
<a class="header-anchor-link" href="#%E4%B8%BB%E3%81%AA%E6%A9%9F%E8%83%BD" aria-hidden="true"></a> 主な機能</h2>
<ul data-line="13" class="code-line">
<li data-line="13" class="code-line">Docコメントに記載されたユビキタス言語、コンテキスト、説明、該当箇所へのリンクを含むHTMLを生成します。</li>
<li data-line="14" class="code-line">出力されたHTMLをGithub Pagesでホスティングすることでユキビタス言語表をチームに公開できます。</li>
</ul>
<p data-line="16" class="code-line">出力されるHTMLのデザインサンプルは下記をご参照ください！<br style="display:none">
<span class="embed-block zenn-embedded zenn-embedded-card"><iframe id="zenn-embedded__a259032a9940c" src="https://embed.zenn.studio/card#zenn-embedded__a259032a9940c" data-content="https%3A%2F%2Fglider2355.github.io%2Fubi-doc%2F" frameborder="0" scrolling="no" loading="lazy"></iframe></span><a href="https://glider2355.github.io/ubi-doc/" style="display:none" target="_blank" rel="nofollow noopener noreferrer">https://glider2355.github.io/ubi-doc/</a></p>
<h2 id="%E8%87%AA%E5%8B%95%E7%94%9F%E6%88%90%E3%81%99%E3%82%8B%E3%83%A1%E3%83%AA%E3%83%83%E3%83%88" data-line="19" class="code-line">
<a class="header-anchor-link" href="#%E8%87%AA%E5%8B%95%E7%94%9F%E6%88%90%E3%81%99%E3%82%8B%E3%83%A1%E3%83%AA%E3%83%83%E3%83%88" aria-hidden="true"></a> 自動生成するメリット</h2>
<p data-line="20" class="code-line">Docコメントでユビキタス言語表を生成するメリットはいくつかあると考えています。</p>
<h3 id="1.-%E3%83%89%E3%82%AD%E3%83%A5%E3%83%A1%E3%83%B3%E3%83%88%E3%81%A8%E3%82%BD%E3%83%BC%E3%82%B9%E3%82%B3%E3%83%BC%E3%83%89%E3%81%AE%E7%B4%90%E4%BB%98%E3%81%91" data-line="22" class="code-line">
<a class="header-anchor-link" href="#1.-%E3%83%89%E3%82%AD%E3%83%A5%E3%83%A1%E3%83%B3%E3%83%88%E3%81%A8%E3%82%BD%E3%83%BC%E3%82%B9%E3%82%B3%E3%83%BC%E3%83%89%E3%81%AE%E7%B4%90%E4%BB%98%E3%81%91" aria-hidden="true"></a> 1. ドキュメントとソースコードの紐付け</h3>
<p data-line="23" class="code-line">Docコメントを基に自動生成されるため、ドキュメントがソースコードが紐づけされ、管理しやすくなります。</p>
<h3 id="2.-%E3%82%BD%E3%83%BC%E3%82%B9%E3%82%B3%E3%83%BC%E3%83%89%E3%81%AE%E8%A9%B2%E5%BD%93%E7%AE%87%E6%89%80%E3%81%8C%E8%A6%8B%E3%81%A4%E3%81%91%E3%82%84%E3%81%99%E3%81%84" data-line="25" class="code-line">
<a class="header-anchor-link" href="#2.-%E3%82%BD%E3%83%BC%E3%82%B9%E3%82%B3%E3%83%BC%E3%83%89%E3%81%AE%E8%A9%B2%E5%BD%93%E7%AE%87%E6%89%80%E3%81%8C%E8%A6%8B%E3%81%A4%E3%81%91%E3%82%84%E3%81%99%E3%81%84" aria-hidden="true"></a> 2. ソースコードの該当箇所が見つけやすい</h3>
<p data-line="26" class="code-line">HTMLには該当するソースコードのリンクが含まれており、ユビキタス言語の定義がどこで使用されているのかを簡単に特定できます。</p>
<h3 id="3.-ai%E3%81%AB%E3%82%88%E3%82%8B%E7%90%86%E8%A7%A3%E3%81%AE%E5%90%91%E4%B8%8A%EF%BC%9F%EF%BC%9F" data-line="28" class="code-line">
<a class="header-anchor-link" href="#3.-ai%E3%81%AB%E3%82%88%E3%82%8B%E7%90%86%E8%A7%A3%E3%81%AE%E5%90%91%E4%B8%8A%EF%BC%9F%EF%BC%9F" aria-hidden="true"></a> 3. AIによる理解の向上？？</h3>
<p data-line="29" class="code-line">Docコメントにユビキタス言語を明示することで、Copilot等がユビキタス言語を理解してくれる。。。かもしれません。</p>
<h2 id="%E4%BD%BF%E3%81%84%E6%96%B9%E3%81%AE%E7%B4%B9%E4%BB%8B" data-line="31" class="code-line">
<a class="header-anchor-link" href="#%E4%BD%BF%E3%81%84%E6%96%B9%E3%81%AE%E7%B4%B9%E4%BB%8B" aria-hidden="true"></a> 使い方の紹介</h2>
<h3 id="1.-doc%E3%82%B3%E3%83%A1%E3%83%B3%E3%83%88%E3%81%A7%E3%83%A6%E3%83%93%E3%82%AD%E3%82%BF%E3%82%B9%E8%A8%80%E8%AA%9E%E3%82%92%E8%A8%98%E8%BC%89%E3%81%99%E3%82%8B" data-line="33" class="code-line">
<a class="header-anchor-link" href="#1.-doc%E3%82%B3%E3%83%A1%E3%83%B3%E3%83%88%E3%81%A7%E3%83%A6%E3%83%93%E3%82%AD%E3%82%BF%E3%82%B9%E8%A8%80%E8%AA%9E%E3%82%92%E8%A8%98%E8%BC%89%E3%81%99%E3%82%8B" aria-hidden="true"></a> 1. Docコメントでユビキタス言語を記載する</h3>
<p data-line="34" class="code-line">ユビキタス言語を設定したいクラスにDocコメントを記載します。</p>
<p data-line="36" class="code-line">Example(PHP, Java, Kotlin)</p>
<div class="code-block-container"><pre><code class="code-line" data-line="37">/**
 * @ubiquitous オーダー
 * @context ショップ
 * @description 顧客の注文書を表します。
 */
class Order
</code></pre></div><p data-line="46" class="code-line">Example(Ruby)</p>
<div class="code-block-container"><pre><code class="code-line" data-line="47"># @ubiquitous オーダー
# @context ショップ
# @description 顧客の注文書を表します。
class Order
</code></pre></div><h3 id="2.-%E3%83%AA%E3%83%9D%E3%82%B8%E3%83%88%E3%83%AA%E3%81%AE%E8%A8%AD%E5%AE%9A" data-line="54" class="code-line">
<a class="header-anchor-link" href="#2.-%E3%83%AA%E3%83%9D%E3%82%B8%E3%83%88%E3%83%AA%E3%81%AE%E8%A8%AD%E5%AE%9A" aria-hidden="true"></a> 2. リポジトリの設定</h3>
<p data-line="55" class="code-line">Github ActionsのPR作成を許可します。<br>
Setting &gt; Actions &gt; Generalで下記のようにPR作成を許可する必要があります。</p>
<p data-line="58" class="code-line"><img src="https://storage.googleapis.com/zenn-user-upload/46f80c11ab4f-20250302.png" loading="lazy" class="md-img"></p>
<p data-line="60" class="code-line">Github PagesでHTMLの生成先のディレクトリを指定します。<br>
下記の画像ではmainブランチのdocsディレクトリのHTMLをホスティングしています。<br>
<img src="https://storage.googleapis.com/zenn-user-upload/bd3af12c8e79-20250302.png" loading="lazy" class="md-img"></p>
<h3 id="3.-github-actions%E3%81%AE%E8%A8%AD%E5%AE%9A" data-line="64" class="code-line">
<a class="header-anchor-link" href="#3.-github-actions%E3%81%AE%E8%A8%AD%E5%AE%9A" aria-hidden="true"></a> 3. GitHub Actionsの設定</h3>
<p data-line="65" class="code-line"><a href="https://github.com/Glider2355/ubi-doc?tab=readme-ov-file#adding-the-github-action" target="_blank" rel="nofollow noopener noreferrer">README</a>を参考にGithub Actionsを設定します。<br>
ここでは各stepsの簡略的な記載内容を説明します！</p>
<ul data-line="68" class="code-line">
<li data-line="68" class="code-line">steps
<ul data-line="69" class="code-line">
<li data-line="69" class="code-line">Checkout repository</li>
<li data-line="70" class="code-line">UbiDoc
<ul data-line="71" class="code-line">
<li data-line="71" class="code-line">ユビキタス言語表のHTMLを生成します。</li>
<li data-line="72" class="code-line">output_dirは出力先のディレクトリを設定してください。</li>
</ul>
</li>
<li data-line="73" class="code-line">Check for differences in ubi-doc directory
<ul data-line="74" class="code-line">
<li data-line="74" class="code-line">生成されたHTMLと現在のdiffを確認します。</li>
<li data-line="75" class="code-line">diffがない場合はその時点で終了します。</li>
<li data-line="76" class="code-line">生成先のディレクトリを指定する必要があります。</li>
</ul>
</li>
<li data-line="77" class="code-line">Close existing auto-generated HTML PRs
<ul data-line="78" class="code-line">
<li data-line="78" class="code-line">過去に自動作成されたOpenのPRがあれば自動でクローズします。</li>
</ul>
</li>
<li data-line="79" class="code-line">Create Pull Request (via gh CLI)
<ul data-line="80" class="code-line">
<li data-line="80" class="code-line">生成されたHTMLを元にPRを作成します。</li>
<li data-line="81" class="code-line">下記のように設定すると自動マージされます。</li>
</ul>
</li>
</ul>
</li>
</ul>
<div class="code-block-container"><pre class="language-yml"><code class="language-yml code-line" data-line="82"><span class="token punctuation">-</span> <span class="token key atrule">name</span><span class="token punctuation">:</span> Create PR
    <span class="token key atrule">run</span><span class="token punctuation">:</span> <span class="token punctuation">|</span><span class="token scalar string">
      PR_URL=$(gh pr create \
        --base main \
        --head "$BRANCH_NAME" \
        --title "Add generated HTML via GitHub Actions" \
        --body "This Pull Request includes the latest auto-generated HTML files." \
        --json url -q .url)
      echo "PR_URL=$PR_URL" &gt;&gt; $GITHUB_ENV</span>
    <span class="token key atrule">env</span><span class="token punctuation">:</span>
      <span class="token key atrule">GH_TOKEN</span><span class="token punctuation">:</span> $<span class="token punctuation">{</span><span class="token punctuation">{</span> secrets.GITHUB_TOKEN <span class="token punctuation">}</span><span class="token punctuation">}</span>

<span class="token punctuation">-</span> <span class="token key atrule">name</span><span class="token punctuation">:</span> Auto merge PR
    <span class="token key atrule">run</span><span class="token punctuation">:</span> <span class="token punctuation">|</span><span class="token scalar string">
      gh pr merge --auto --squash "$PR_URL"</span>
    <span class="token key atrule">env</span><span class="token punctuation">:</span>
      <span class="token key atrule">GH_TOKEN</span><span class="token punctuation">:</span> $<span class="token punctuation">{</span><span class="token punctuation">{</span> secrets.GITHUB_TOKEN <span class="token punctuation">}</span><span class="token punctuation">}</span>
</code></pre></div><h2 id="%E3%81%95%E3%81%84%E3%81%94%E3%81%AB" data-line="102" class="code-line">
<a class="header-anchor-link" href="#%E3%81%95%E3%81%84%E3%81%94%E3%81%AB" aria-hidden="true"></a> さいごに</h2>
<p data-line="103" class="code-line">ユビキタス言語をDocコメントで管理する例は、筆者の知る限りではあまり見られません。<br>
しかし、スプシ等で管理するのもそれはそれで大変です。コードとスプシが乖離する可能性があります。<br>
「コードと乖離しないようにユビキタス言語を管理したい！」という方がいればぜひ使ってみてください！</p>


Github Actionsでユビキタス言語を管理しよう！

1. ドキュメントとソースコードの紐付け

2. ソースコードの該当箇所が見つけやすい

1. Docコメントでユビキタス言語を記載する

Discussion