这是正在进行的系列文章的第二部分，该系列文章着眼于从头开始构建自定义文档门户，该门户使用 Swagger 开源工具以及我们的专业平台 - Swaggerhub。
如果您还没有看过关于设置和构建初始框架的第一部分，可以在此处找到 - 或者包含完整代码的存储库可以在此处找到，并托管在此处。
在本系列的第一部分中，我们专注于创建文档门户时将使用的环境和工具，以及构建初始组件以动态获取和呈现文档。现在我们已经构建了基础层 - 我们可以开始研究自定义此门户，使其真正成为我们自己的门户。
与 Web 开发中的任何事情一样 - 我们有很多方法可以做到这一点。理想情况下，我们将创建一个自定义模板，我们可以将其传递给 SwaggerUI 组件（而不是当前的“baseLayout”），以真正更改页面布局及其样式，这将在本系列的另一部分中进行探讨。对于我们的初始用例，我们将只探索一些我们应该调整的大型组件和类，以开始使文档看起来不那么“千篇一律”。
设置
对于我们的演示站点，我们设想一个臭名昭著的银河帝国正在进行数字化转型 - 希望这将席卷整个星系并帮助他们实现即将到来的扩张目标。随着大型组织内的不同团队和团体从传统的单体开发流程中分离出来，并开始公开他们自己的内部服务，因此需要在单个位置提供所有这些服务的文档，并且从样式角度来看，要与银河帝国的整体品牌和“感觉”相匹配。
目前，我们在明亮的白色背景上使用了 SwaggerUI 组件的基本样式，这很实用，但与组织的整体外观和感觉形成对比。我们也没有包含任何图像或徽标来作为我们品牌的视觉辅助工具。幸运的是，我们获得了可供使用的调色板，这将使任务变得更容易，并且拥有一个在整个组织中使用的字体库和徽标。
在接下来的几个步骤中，我们将快速为站点构建一个较深的配色方案，并更新我们的侧边栏标题，使其包含自定义字体、徽标和子标题。如上所述，这不是理想的方法 - 但作为一种相对简单的方法来同时使用 SwaggerUI 的默认样式和我们自己的 CSS 选项，它暂时有效。
更新页面样式
我们应该首先查看的是当前样式表的结构 - 基于我们在之前的教程中构建的内容，我们知道可以开始更新页面主体和侧边栏等基本组件，而中央“文档”窗格必须根据 SwaggerUI 组件的现有名称和结构进行更新。
让我们看看如何更新侧边栏以与我们的最终愿景保持一致。这应该非常简单，因为我们有一个单独的侧边栏主体类 side-bar 并且链接共享一个通用类名 api-link。目前，这些都位于同一个 App.css 文件中，这对于我们的初始设置来说效果很好。
为了使事情更易于管理，让我们创建一个 /css 文件夹，并将除 index.css 之外的所有 CSS 文件都移到该文件夹，因为 create-react-app 需要此文件。随着应用程序开始增长，我们需要保持组件和依赖项的组织性，并减少混乱。请务必在 index.css 中添加所需的导入语句，以从其新位置加载文件。
我们也可以借此机会引入我们从 SwaggerUI 组件加载的依赖样式表。与其回头查看我们的 /node_modules 文件夹（这会根据通过某些主机服务构建的方式产生问题），不如将样式表拉入我们刚刚创建的 /css 文件夹，使其与我们其他所需文件相邻。此文件目前位于 /node_modules/swagger-ui/dist/swagger-ui.css，也可以从下面的 gist 中复制。
很混乱 - 这也是我们将在以后的文章中探讨从头开始构建模板的主要原因。现在，我们可以继续调整 side-bar 样式，然后再继续处理标题和文档样式。我们有上面颜色列表中的一组颜色，因此我们可以继续更新 side-bar.css 文件。
更新非常简单，我们将在下一节中处理标题 - 目前我们只是
- 使侧边栏背景变暗
- 反转文本颜色，使其在深色背景下突出显示
- 侧边栏面板中的新字体
这些更改中的大多数都应该很容易自定义 - 对于自定义字体（现在和以后使用），请确保将 link 语句添加到浏览器中呈现的最高级别 .html 页面。此项目中显示的字体来自 Google Fonts - 但任何字体都适用。
我们现在应该有一个修改后的侧边栏，但页面的其余部分应该看起来非常标准 - 在我们更新页面主体之前，我们可以向侧边栏标题添加一些更自定义的元素，使其与页面的其余样式保持一致。
更新标题
我们知道我们将添加图像并更新侧边栏标题的布局，之后我们将对样式表进行一些调整，以使所有内容正确显示。我们应该在这里关注几个类，即 side-bar-header 以及其中的 h1 元素。从徽标图像开始 - 我们可以将其存储在与其余文件相同的 /src 目录中，但让我们假设我们有一个 CMS 或图像存储库来存储这些文件 - 因此，如果这些文件被更新，我们无需更改应用程序端的任何内容。我们知道，我们已经有一些信息存储在之前创建的 organization_config.json 文件中，并且只需要确保 JSON 对象中具有当前数据即可。
现在我们需要更新侧边栏组件以显示此新信息。打开 Sidebar.js 并更新它以考虑子标题和图像。
我们已经通过引入 JSON 对象完成了大部分繁重的工作，我们真正需要做的只是为这些值提供一些存储位置
- 添加了 img 并将其指向远程 URL
- 以 h3 元素的形式添加了子标题
最后，我们应该更新 CSS 文件以适应新的元素。一些小的改动可以使页面更整洁，并赋予页面一些急需的上下文信息。
至此，侧边栏应该看起来相当不错了，我们更新了样式，并在标题部分引入了一些新的信息进行展示。该过程的最后一步是将 SwaggerUI 的样式更改为在深色背景上能很好地呈现。
更新文档样式
最后，我们可以将注意力转向文档组件本身。目前，它可能看起来非常难以使用 - 深色背景上的深色字体。SwaggerUI 在选择要渲染的样式表方面非常激进 - 传统上，我们应该能够加载自定义样式，然后加载我们引入的默认样式表，CSS 层级结构会将我们的更改覆盖在内置的样式之上。不幸的是，无论导入顺序如何，SwaggerUI 的样式都被认为是真理，这意味着为了更新样式，我们必须非常精细地进行更改。
最好的方法是使用像 Chrome 开发者工具检查视图这样的工具，并根据被遮挡的元素抓取类名。下面的样式表有一组核心的文本和样式元素，这些元素被更新为在早先实现的深蓝色背景上清晰地呈现。
从高层次来看，这些更改非常简单明了
- 我们使用
.swagger-ui .info 获取所有信息块，并引入白色背景，添加一些填充使其有呼吸的空间。.description p 更新描述文本以在白色背景上显示。
- 所有 op-block 标签（OpenAPI 定义中的标签）都切换为以白色显示
- 操作描述、标题、名称等被逐个抓取并以白色显示
- 页面底部的模型部分被更新为使边缘变得方正，并在深色页面上更清晰地显示。
回顾一下
当我们重新加载页面时，它应该与我们最初实现的设计大相径庭 - 更符合本例中组织的整体“外观”。回想起来，很高兴我们能够依靠 SwaggerUI 库来处理大部分样式，并且我们可以选择要更新的内容 - 但它很容易变得非常混乱，非常快。使用检查工具之类的东西可以帮助我们到达我们需要的地方，但最终会给我们一个非常僵化和精细的解决方案，新项目人员很难对其进行修改。
幸运的是，我们有解决方案！SwaggerUI 允许传递自定义布局 - 因此，我们可以开始按照我们认为合适的方式移动和设置整个页面的样式，而不是使用本例中的默认“BaseLayout”。这将使我们能够更轻松地设置页面样式，还可以考虑屏幕上数据的新排列方式 - 例如，与我们目前使用的列视图相反的并排视图（在像 Slate 这样的库中很常见）。我们将在接下来的文章中从头开始进行此操作。
目前，希望这篇文章为您提供了开始在最初设置的 SwaggerUI 默认值之上添加一些自定义样式和信息的基础。本系列的下一篇文章探讨了如何快速将我们构建的应用程序部署到几个不同的主机选项（例如 Netlify） - 以及通过添加环境变量和经过身份验证的 API 调用链接回 Swaggerhub 中的私有组织。