OSAMU NAKAMURA

とりあえずソースリーディング
調査バージョン：https://github.com/Redocly/redocly-cli/tree/%40redocly/cli%401.25.9

OSAMU NAKAMURA

Issueあり

OSAMU NAKAMURA

ワークアラウンド: タグとして記述する。

description 内で<SchemaDefinition>でスキーマを参照しつつ、説明文を追記する。

tags:
  - name: test_tag_name
    x-displayName: Test Model
    description: |
      スキーマの説明をここに書く
      <SchemaDefinition schemaRef="#/components/schemas/MySchema" />

showExample={true} とすれば、example がサイドバーに表示される。
schemaに x-tags を指定するよりは記述量が多いのが難点

OSAMU NAKAMURA

SchemaDefinitionに showDescriptionみたいな属性があればよいのだが・・・

もしくは　<Markdown ref="#/components/schemas/MySchema/description" /> みたいに
適当なMarkdownをレンダリングできれば、schema.description をそのままレンダリングできてメンテが楽になる。

OSAMU NAKAMURA

いったん build から追う

index.ts から呼び出すハンドラ、 handlerBuildCommand を呼び出す
redocの loadAndBundleSpec を呼び出す
getPageHTML を呼び出す

OSAMU NAKAMURA

redoc.Redoc がReactComponent になっている
components ディレクトリ

がSpecに対応していそう
Redoc
ApiInfo

ContentItems
ContentItem
SectionItem (tag, section)
OperationItem (operation)
Operation:  pathItem に対応するのでこっちではなさそう

OSAMU NAKAMURA

ContentItems

ソース

ContentItem

content = ...
<Section id={item.id}>
  {content}
</Section>
<ContentItems items={item.items} />

content は item.type に応じて SectionItem か OperationItem のいずれかになる。

SectionItem

type: "tag", "section"

<>
    <Row>
        <MiddlePanel>
            <Header>
                <ShareLink />
                {name}
            </Header>
        </MiddlePanel>
    </Row>
    <AdvanceMarkdown
        parentId=
        source={description || ''}
        htmlWrap={middlePanelWrap}
    />
    {externalDocs && (
        <Row>
            <MiddlePanel>
                <ExternalDocumentation />
            </MiddlePanel>
        </Row>

OperationItem

type: "operation"

Hidden comment

OSAMU NAKAMURA

redoc を修正して期待通りの動作にできないか試してみる

OSAMU NAKAMURA

redocを修正してビルドすればいいんじゃないかと、 npm i ../oss/redoc のようにしてみたが、動作せず。
template 中で redoc をCDNから読み込んでいるため書き直す必要がありそう。

  <script src="https://cdn.redocly.com/redoc/latest/bundles/redoc.standalone.js"></script>

OSAMU NAKAMURA

preview-docs は template を引数に取らないので、多少手順を踏む必要がある。

@node_modules/@redocly/cli/lib/commands/preview-docs/preview-server/preview-server.ts の getPageHTML 中の readocHead の定義を置き換える

+ <script src="/redoc.standalone.js" />
-  <script src="${
-    useRedocPro
-      ? 'https://cdn.redocly.com/reference-docs/latest/redocly-reference-docs.min.js'
-      : 'https://cdn.redocly.com/redoc/latest/bundles/redoc.standalone.js'
-  }"></script>

@node_modules/@redocly/cli/lib/commands/preview-docs/preview-server/default.hbs を修正してもOK

@node_modules/@redocly/cli/lib/commands/preview-docs/preview-server/preview-server.ts の filePath に redoc.standalone.js を追加

                '/hot.js': path.join(__dirname, 'hot.js'),
+               '/redoc.standalone.js': path.join(__dirname, 'redoc.standalone.js'),

redoc を修正したあと npm run bundle で生成した bundles/redoc.standalone.js を上記の preview-server ディレクトリに格納する(ln -s だと楽）