Stoplight Elements WebComponents 原生 WEB 组件化技术生成 Swagger优美界面

zimoyin2026-04-25 9:01

Stoplight 的设计充分考虑了现代 API 工作流程，提供直观的界面和周到的功能，为整个 API 设计生命周期提供支持。能够利用从 OpenAPI 文档生成的可嵌入 Web 组件，构建高度定制化的交互式 API 文档。

原本的 Swagger 界面过于难看，其余组件大部分是VUE或者Spring的依赖库。对于不是这两种技术的原生Web开发来说，想要一个好看的Swagger过于麻烦，甚至找不到合适的。

Stoplight Elements 提供了使用 Web Components 的库能够为原生的Web开发直接使用现成的Openapi页面，无需要复杂CSS与JS

1. 引入

Stoplight 只需要引入一份JS与CSS库即可

html 复制代码

<script src="https://unpkg.com/@stoplight/elements/web-components.min.js"></script>
<link rel="stylesheet" href="https://unpkg.com/@stoplight/elements/styles.min.css">

2. 使用

要使用Stoplight 只需要在 HTML 写一个div 标签，并指定css以及能被js带去的id 即可

html 复制代码

<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>CSWM 智能称重设备 API - Elements</title>
    <!-- 引入 Elements 样式 -->
    <link rel="stylesheet" href="https://unpkg.com/@stoplight/elements/styles.min.css">
    <style>
        body { margin: 0; height: 100vh; }
    </style>
</head>
<body>
<!-- Elements 容器 -->
<div id="api-reference" class="sl-elements-root"></div>

<!-- 引入 Elements JS -->
<script src="https://unpkg.com/@stoplight/elements/web-components.min.js"></script>
<script>
    const apiDescriptionDocument = '/client-swagger/openapi.yaml';

    // 初始化 Elements
    customElements.whenDefined('elements-api').then(() => {
        const el = document.createElement('elements-api');
        el.apiDescriptionUrl = apiDescriptionDocument;
        el.layout = 'sidebar';
        el.router = 'hash';
        el.hideTryIt = false; // 显示调试按钮
        el.hideSchemas = false;

        document.getElementById('api-reference').appendChild(el);
    });
</script>
</body>
</html>