时尚的 API
在这篇博文中，我们将了解 OpenAPI 和 Swagger UI Quarkus 扩展（1.10+ 版本）中提供的新样式和其他新选项。
下面所有示例的源代码均在此处提供。
样式
默认样式
Swagger UI 的默认样式已从原始 Swagger UI 更改为带有 Quarkus 品牌标识的页面
在这篇文章中，我们主要关注 Swagger UI，但样式选项也适用于GraphQL UI 和Health UI。
主题
现在可以在配置中使用Swagger UI 主题，默认主题为“feeling blue”。
您可以通过设置 quarkus.swagger-ui.theme 属性来更改主题，例如
quarkus.swagger-ui.theme=outline
您也可以返回到原始（原生）Swagger UI 主题
quarkus.swagger-ui.theme=original
可用主题选项
-
feeling-blue (默认)
-
original
-
flattop
-
material
-
monokai
-
muted
-
newspaper
-
outline
Logo
作为自定义品牌的一部分，您可以提供自己的 logo 来替换 Quarkus logo。例如，假设您拥有一家生产所有产品（ACME）的公司，并且您正在使用 REST Services 作为在线商店，并希望为 Swagger UI 页面打上品牌标识。
| logo 更改不支持热重载，请记住浏览器缓存，您可能需要强制刷新您的浏览器。 |
要提供您自己的 logo，您需要将一个名为 logo.png 的文件放在 src/main/resources/META-INF/branding 目录中。
样式
您可以进一步提供自己的 style.css 来微调品牌标识。例如，要将 Swagger UI 屏幕的 topbar 更改为符合 ACME 的公司颜色。
html{
box-sizing: border-box;
overflow: -moz-scrollbars-vertical;
overflow-y: scroll;
}
*,
*:before,
*:after
{
box-sizing: inherit;
}
body{
margin:0;
background: white;
}
.swagger-ui .topbar {
background-color: whitesmoke; (1)
}
#footer {
background-color: whitesmoke;
font-family:sans-serif;
color:#4da32c;
font-size:70%;
text-align: center;
}| 1 | 在此处设置 topbar 的背景颜色。 |
您可以在此 css 文件中更改任何样式元素，您需要将此名为 style.css 的文件放在 src/main/resources/META-INF/branding 目录中。
其他样式选项
您还可以设置 HTML 标题，并添加页脚。
quarkus.swagger-ui.title=ACME API
quarkus.swagger-ui.footer=© 2020 . ACME以及其他可以通过配置属性设置的 OpenAPI Header 字段（如本文所述）。
mp.openapi.extensions.smallrye.info.title=ACME online store API
mp.openapi.extensions.smallrye.info.version=1.0.0
mp.openapi.extensions.smallrye.info.description=We make everything, and sell it online
mp.openapi.extensions.smallrye.info.contact.email=it@acme.com
mp.openapi.extensions.smallrye.info.contact.name=ACME IT
mp.openapi.extensions.smallrye.info.contact.url=https://www.acme.com
mp.openapi.extensions.smallrye.info.license.name=Apache 2.0
mp.openapi.extensions.smallrye.info.license.url=https://apache.ac.cn/licenses/LICENSE-2.0.htmlUI 现在已完全品牌化。
其他 Swagger UI 选项
Quarkus（1.10+ 版本）的另一项新功能是能够设置 Swagger UI 中提供的任何配置选项。例如，我们可以设置 urls 并将 petstore（作为默认选中的选项）添加到 Swagger UI。
quarkus.swagger-ui.urls.default=/openapi
quarkus.swagger-ui.urls.petstore=https://petstore.swagger.io/v2/swagger.json
quarkus.swagger-ui.urls-primary-name=petstore这将更改 topbar，使其具有一个带有提供 url 的下拉框。
另一个例子，supportedSubmitMethods 可以隐藏某些 HTTP 方法类型的 Try it out 按钮。
quarkus.swagger-ui.supported-submit-methods=get请注意下方 POST 请求上缺少 Try it out 按钮。
所有其他 Swagger UI 选项现在都可以用于配置 UI。
其他小型新功能
我将向您介绍 OpenAPI 和 Swagger UI 中的两项小型新功能：添加 Health Endpoints 的能力以及在运行时禁用 UI 和/或 Schema 的能力。
将 Health API 添加到 Open API
如果您正在使用 smallrye-health 扩展，您可以将 Health Endpoints 添加到 OpenAPI。
quarkus.health.openapi.included=true
运行时禁用
如果您将 UI 添加到您的应用程序中 (quarkus.swagger-ui.always-include=true)，现在可以在启动应用程序时禁用它。
java -jar -Dquarkus.swagger-ui.enable=false target/yourapp-1.0.0-runner.jar这将导致 Swagger UI 页面返回 HTTP 404 (Not Found)。
同样，您可以通过执行以下操作来禁用 Schema（通常在 /openapi 下）。
java -jar -Dquarkus.smallrye-openapi.enable=false target/yourapp-1.0.0-runner.jar
