用k8s私有化部署docsify做开放API平台

news2024/9/28 2:16:37

文章目录

  • 1、API开放平台
  • 2、实现思路
  • 3、用docsify实现
  • 4、一些坑
    • 坑1：nginx转发实现跳转
    • 坑2：点击跳转不能精准跳
    • 坑3：md文档页内跳转与跨文档跳转
    • 坑4：插件做目录的折叠收起
    • 坑5：统一目录

做完了一个API开放平台的需求，整理下一些实现与踩坑：

1、API开放平台

参照模板：【工行的API开放平台】

https://open.icbc.com.cn/icbc/apip/service_detail.html?service_id=S1000#

API开放平台，用于给第三方系统做接入用，开放的自然也是用于对接的那部分API。主要有两类：

  • 只做个API文档的plus版本，不支持在线调用
  • 可在线进行调试和调用

前者简单，后者得考虑鉴权、限流等问题。

2、实现思路

关于第一类API开放平台

这类API开放平台不需要考虑在线调用，能展示就行，实现方式可考虑：

  • 借助第三方框架docsify：易用，给md，docsify去渲染出前端页面
  • 借助第三方框架vuepress
  • 在自己系统里实现一个API维护页面，前端根据UI的图去定制做页面

关于第三种的具体思路：

在这里插入图片描述

关于API文档内容的维护，可考虑采用上传word文档或者在线富文本框的方式，提到后端，后端转md或其他前端需要的格式后，返回给前端。

在这里插入图片描述

这种实现类似工行的开放平台，优点是灵活，自己爱咋展示咋展示，维护、上下架接口、编辑、删除都可以做成一个前端页面，可以在线操作，不涉及热部署。缺点是开发量不小。

关于第二类API开放平台

第二类API开放平台，需要做在线调用，那调用者的鉴权、限流、防恶意调用等问题需要考虑到。

在这里插入图片描述

实现方式：

  • 采用easyopen框架
//参考文档
https://durcframework.gitee.io/easyopen/#/files/110_%E7%94%9F%E6%88%90%E6%96%87%E6%A1%A3%E9%A1%B5%E9%9D%A2?t=1572484542437
  • 采用SOP框架（涉及Nacos，很适配SpringCloud项目）
//参考文档
https://durcframework.gitee.io/sop/#/files/10041_%E7%BC%96%E5%86%99%E6%96%87%E6%A1%A3?t=1616211903049&id=%e6%9f%a5%e7%9c%8b%e6%96%87%e6%a1%a3

https://gitee.com/durcframework/SOP/wikis/%E6%9E%B6%E6%9E%84%E5%9B%BE

在这里插入图片描述

3、用docsify实现

关于docsify的简单入门，看官方文档就行，初始化的目录结构和文档，如果操作npm有坑被卡，其实自己手动创建个目录，复制个index.html就行。这里展示docsify私有化部署到自己系统。k8s资源的yaml文件架子，Service如下，类型用了NodePort，部署完直接访问也可以：

apiVersion: v1
kind: Service
metadata:
  name: api-open-platform-service
  namespace: your-ns
spec:
  type: NodePort
  ports:
    - protocol: TCP
      port: 3000
      targetPort: 3000
      nodePort: 30070
  selector:
    app: api-open-platform-deployment

Pod控制器Deployment：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api-open-platform-deployment
  namespace: your-ns
spec:
  replicas: 1
  selector:
    matchLabels:
      app: api-open-platform-deployment
  template:
    metadata:
      labels:
        app: api-open-platform-deployment
    spec:
      dnsPolicy: ClusterFirst
      containers:
        - name: api-open-platform-deployment
          image: your-diy-image:tag
          ports:
            - containerPort: 3000

Dockerfile，ADD和COPY相关md到工作目录/docs下

FROM node:latest

MAINTAINER code-9527@csdn

LABEL description="Dockerfile for build Docsify."

ENV TZ=Asia/Shanghai

RUN mkdir -p /docs

WORKDIR /docs

COPY . /docs/

//下面这句可选，配置npm代理的
//ARG registry=http://公司镜像仓库/repository/npm-all/

//RUN npm config set registry $registry

RUN npm install -g docsify-cli@latest

EXPOSE 3000/tcp

ENTRYPOINT docsify serve .

当前项目的目录结构如下，对应Dockerfile就是cd到docsify目录下ADD圈起来的文件到容器的/docs下

在这里插入图片描述

这里直接把docsify用到的静态资源（css样式、js插件）都搬到项目里了，不用每次去下载，加快渲染速度。最后，核心的index.html，官方最初版本：

https://docsify.js.org/#/quickstart?id=manual-initialization

调整下，把css和js改为上面的static目录，加一段目录折叠代码（官方的目录插件调半天不能收起和折叠），再加一个basePath方便后面nginx做转发嵌入到自己的系统，实现点击跳转。

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Document</title>
    <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
    <meta name="description" content="Description">
    <meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0">
    <link rel="stylesheet" href="./static/buble.css">
    <style>
        /* 添加CSS样式以控制折叠效果 */
        .sidebar ul.collapsed {
            display: none;
    </style>
</head>
<body>
<div id="app"></div>
<script>
    window.$docsify = {
        name: '',
        repo: ''
    }
</script>
<!-- Docsify v4 -->
<script>
    window.$docsify = {
        basePath: '/api-doc/',
        loadSidebar: true
    }
    window.addEventListener('load', () => {
        const tocHeaders = document.querySelectorAll('.sidebar li');
        tocHeaders.forEach(header => {
            const subItems = header.nextElementSibling;
            if (subItems) {
                subItems.classList.add('collapsed');
            }
            header.addEventListener('click', (e) => {
                // 获取当前标题对应的下一个UL列表（即二级标题及其子级）

                if (subItems) {
                    subItems.classList.toggle('collapsed');
                }
            });
        });
    });
</script>
</script>


<script src="./static/docsify.min.js"></script>
<script src="./static/docsify-copy-code.min.js"></script>
<script src="./static/docsify-sidebar-collapse.min.js"></script>
</body>
</html>

build镜像后访问IP:30070即可

4、一些坑

坑1：nginx转发实现跳转

最终需要iframe内嵌docsify的页面到自己系统，上面部署的docsiy是http，自己系统https，访问时被浏览器拦了：

The page at https://xxx was loaded over HTTPS,but requested an insecure frame http://xx.
The request has been blocked,the content must be served over HTTPS

想把上面的部署改成https，得再搞个ingress+secret证书，太麻烦，这里用nginx垫一层：

location /api-doc/ {
    proxy_pass   http://api-open-platform-service:3000/;
}

注意这里location后面监听地址api-doc/，最后面有斜杠和没斜杠的坑。

坑2：点击跳转不能精准跳

部署完，访问时，点击目录跳转，发现跳转有时受上次滚动条位置的影响，跳不准文章开始点，采用锚点精准跳：

//在跳转的目的位置定义锚点
<a id="section1"></a>

//使用锚点
[快速入门](README.md#section1)

加了锚点在页内跳转和跨文档跳转都可以：

[认证服务](auth/auth.md#section1)

坑3：md文档页内跳转与跨文档跳转

- [认证服务](auth/auth.md#section1)

    - [功能介绍](auth/auth.md#_1-功能介绍)

如上，想跳转到md某一个章节，除了锚点，也可以使用章节段落，这个 #_1-功能介绍 来自渲染后的前端代码：

在这里插入图片描述

坑4：插件做目录的折叠收起

docsify的侧边栏默认是不能折叠，可以加插件docsify-sidebar-collapse来解决：

<script src="//cdn.jsdelivr.net/npm/docsify-sidebar-collapse/dist/docsify-sidebar-collapse.min.js"></script>
//侧边栏有问题时检查_sidebar.md每行之间不能有空行，以及每个markdown文件必须以#作为标题

想加个 > 来显示收起和展开，可加个css，箭头指示折叠标用：

<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify-sidebar-collapse/dist/sidebar.min.css"/>

文件夹指示折叠标用：

 <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify-sidebar-collapse/dist/sidebar-folder.min.css" />

坑5：统一目录

使用插件，只能在每个md里生成自己的目录，想用统一的目录（不管切到哪个md，侧边栏目录始终不变），可手写_sidebar.md，然后index.html加这个配置：

在这里插入图片描述

_sidebar.md文件样例：

- [快速入门](README.md#section1)

    - [平台简介](README.md#_1-平台简介)
    - [术语介绍](README.md#_2-术语介绍)
    - [服务列表](README.md#_3-服务列表)
    - [接入示例](README.md#_4-接入示例)
      
- [认证服务](auth/auth.md#section1)

    - [功能介绍](auth/auth.md#_1-功能介绍)
       - [功能概述](auth/auth.md#_11-功能概述)
       - [应用场景](auth/auth.md#_12-应用场景)
       - [适用客户](auth/auth.md#_13-适用客户)
    - [快速接入](auth/auth.md#_2-快速接入)
       - [准备](auth/auth.md#_21-准备)
       - [业务流程](auth/auth.md#_22-业务流程)
    - [API列表](auth/auth.md#_3-API列表)
      - [接口1](auth/api/接口1.md#section1)
      - [接口2](auth/api/接口2.md#section1)

- [服务2](service/yourService.md#section1)

    - [功能介绍](service/yourService.md#_1-功能介绍)
        - [功能概述](service/yourService.md#_11-功能概述)
        - [应用场景](service/yourService.md#_12-应用场景)
        - [适用客户](service/yourService.md#_13-适用客户)
    - [快速接入](service/yourService.md#_2-快速接入)
        - [准备](service/yourService.md#_21-准备)
        - [业务流程](service/yourService.md#_22-业务流程)
    - [API列表](service/yourService.md#_3-API列表)
        - [接口1](service/api/接口1.md#section1)
        - [接口2](service/api/接口2.md#section1)

最后，备份下API开放平台一个还不错的API开放平台目录结构：

在这里插入图片描述

在这里插入图片描述

本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若转载，请注明出处：http://www.coloradmin.cn/o/1410078.html

如若内容造成侵权/违法违规/事实不符，请联系多彩编程网进行投诉反馈，一经查实，立即删除！

相关文章

了解云工作负载保护：技术和最佳实践

了解云工作负载保护：技术和最佳实践

云工作负载是指云环境中的应用程序或存储元素&#xff0c;无论是公共云、私有云还是混合云。每个云工作负载都使用云的资源&#xff0c;包括计算、网络和存储。 云工作负载可以多种多样&#xff0c;例如运行应用程序、数据库或托管网站。它们可以是静态的或动态的&#xff0c;…
阅读更多...
MySQL（下）

MySQL（下）

四、事务 一、概念 对数据库的一次执行中有多条sql语句执行。这多条sql在一次执行中&#xff0c;要么都成功执行&#xff0c;要么都不执行。保证了数据完整性。MySQL中只有innodb引擎支持事务。 二、特性 事务是必须满足 4 个条件&#xff08;ACID&#xff09;&#x…
阅读更多...
【pytorch】pytorch学习笔记（续1）

【pytorch】pytorch学习笔记（续1）

p22&#xff1a;1.加减乘除&#xff1a; &#xff08;1&#xff09;add(a,b)&#xff1a;等同于ab。 &#xff08;2&#xff09;sub(a,b)&#xff1a;等同于a-b。 &#xff08;3&#xff09;mul(a,b)&#xff1a;等同于a*b。 &#xff08;4&#xff09;div(a,b)&#xff1a…
阅读更多...
前端 防止浏览器提示记住密码以及自动填充密码

前端 防止浏览器提示记住密码以及自动填充密码

当前端 <input /> 的 type’password‘ 时&#xff0c;浏览器为了优化用户体验&#xff0c;会在表单提交后提示用户记住密码 如果不想要这样的行为&#xff0c;最简单的当然是提示用户自己在浏览器设置中进行相关配置 如果希望在代码层面阻止浏览器提示是否记住密码或者…
阅读更多...
AI开发——探索人工智能时代的无限可能

AI开发——探索人工智能时代的无限可能

在当今信息化时代&#xff0c;人工智能&#xff08;Artificial Intelligence&#xff0c;简称AI&#xff09;以其强大的计算能力和智能分析能力成为科技界的热门话题。AI开发正处于快速发展的阶段&#xff0c;各行业都在积极探索和应用AI技术&#xff0c;推动人工智能时代的到来…
阅读更多...
【c++】高精度算法（洛谷刷题2024）乒乓球详解

【c++】高精度算法（洛谷刷题2024）乒乓球详解

系列文章目录 第一题 乒乓球 视频&#xff1a;http://【洛谷题单 - 算法 - 高精度】https://www.bilibili.com/video/BV1Ym4y1s7BD?vd_source66a11ab493493f42b08b31246a932bbb 目录 系列文章目录 第一题 乒乓球 前言 一、题目以及引领思考 二、题解与代码 1.输入输出案例 …
阅读更多...
查看Pytorch的GPU是否可用

查看Pytorch的GPU是否可用

查看Pytorch的GPU是否可用 import torch torch.cuda.is_available()返回为True表示 Pytorch 的 GPU 可用&#xff0c;返回为False表示 Pytorch 的 GPU 不可用。 其余命令&#xff1a; # 查看cuda是否可用 torch.cuda.is_available() # 返回当前设备索引 torch.cuda.current_d…
阅读更多...
还在纠结怎么选随身WiFi的，看看这个！随身WiFi靠谱榜第一名推荐！哪个随身WiFi最好用

还在纠结怎么选随身WiFi的，看看这个！随身WiFi靠谱榜第一名推荐！哪个随身WiFi最好用

你是不是还在头疼如何挑选一个靠谱好用的随身WiFi呢&#xff1f;市场上的随身WiFi产品五花八门&#xff0c;每次购买随身WiFi都会被坑&#xff0c;差点就失去购买的信心了~别灰心&#xff0c;一篇文章教你如何挑选一个靠谱好用的随身WiFi&#xff01; 一、5大购买原则&#xff…
阅读更多...
C++:缺省参数函数重载

C++:缺省参数函数重载

目录 C/C语言 函数调用的工作原理&#xff1a; 函数调用一般分为两个部分&#xff1a; 缺省参数&#xff1a; 缺省参数的分类&#xff1a; 全缺省参数 半缺省参数 注意事项&#xff1a; 缺省参数与C语言的调用参数对比&#xff1a; 函数重载&#xff1a; 函数重载…
阅读更多...
C++ qt标题栏组件绘制

C++ qt标题栏组件绘制

本博文源于笔者在学习C qt制作的标题栏组件&#xff0c;主要包含了&#xff0c;最小化&#xff0c;最大化&#xff0c;关闭。读者在看到这篇博文的时候&#xff0c;可以直接查看如何使用的&#xff0c;会使用了&#xff0c;然后进行复制粘贴源码部分即可。 问题来源 想要制作…
阅读更多...
【禅道】下载安装及基本流程----【图文并茂】从头到尾讲解

【禅道】下载安装及基本流程----【图文并茂】从头到尾讲解

目录 一 禅道简介 二 下载安装 三 基本流程 3.1添加用户(管理员) 3.2 添加产品 (产品经理) 3.2.1 创建模块 3.2.2 创建计划 3.2.3 创建需求 3.3 添加项目(项目经理) 3.3.1 设置团队 3.3.2 关联产品需求 3.2.3 分配任务 3.3.4 创建版本(研发人员) 3.3.5 提交测试 …
阅读更多...
SecureCRT的安装

SecureCRT的安装

SecureCRT的安装 加强版的串口调试助手 全部默认安装&#xff0c;默认安装在c盘 SecureCRT收费&#xff0c;可以下载Putty安装 后续完善
阅读更多...
关于Spring和缓存雪崩、穿透、击穿、预热的最常见的十道面试题

关于Spring和缓存雪崩、穿透、击穿、预热的最常见的十道面试题

面试题一&#xff1a;什么是缓存雪崩&#xff1f;如何解决缓存雪崩&#xff1f; 缓存雪崩指的是在短时间内&#xff0c;有大量的请求直接查询术后句酷&#xff0c;从而对数据库造成大量的压力&#xff0c;严重情况下可能导致数据库宕机的情况叫做缓存雪崩 我们可以看一下正常…
阅读更多...
k8s架构、工作流程、集群组件详解

k8s架构、工作流程、集群组件详解

目录 k8s概述 特性 作用&#xff08;为什么使用&#xff09; k8s架构 k8s工作流程 k8s集群架构与组件 核心组件详解 Master节点 Kube-apiserver Kube-controller-manager Kube-scheduler 存储中心 etcd Node Kubelet Kube-Proxy 网络通信模型 容器引擎 k8s核…
阅读更多...
【C语言入门】分支和循环

【C语言入门】分支和循环

✨✨欢迎大家来到Celia的博客✨✨ &#x1f389;&#x1f389;创作不易&#xff0c;请点赞关注&#xff0c;多多支持哦&#x1f389;&#x1f389; 所属专栏&#xff1a;C语言 个人主页&#xff1a;Celias blog~ 目录 引言 1. if语句 1.1 if 1.2 else 1.3 if的嵌套 2. 操…
阅读更多...
python 正则表达式学习(1)

python 正则表达式学习(1)

正则表达式是一个特殊的字符序列&#xff0c;它能帮助你方便的检查一个字符串是否与某种模式匹配。 1. 特殊符号 1.1 符号含义 模式描述^匹配字符串的开头$匹配字符串的末尾.匹配任意字符&#xff0c;除了换行符&#xff0c;当re.DOTALL标记被指定时&#xff0c;则可以匹配包…
阅读更多...
计算机设计大赛 协同过滤电影推荐系统

计算机设计大赛 协同过滤电影推荐系统

文章目录 1 简介1 设计概要2 课题背景和目的3 协同过滤算法原理3.1 基于用户的协同过滤推荐算法实现原理3.1.1 步骤13.1.2 步骤23.1.3 步骤33.1.4 步骤4 4 系统实现4.1 开发环境4.2 系统功能描述4.3 系统数据流程4.3.1 用户端数据流程4.3.2 管理员端数据流程 4.4 系统功能设计 …
阅读更多...
工厂HVAC暖通系统如何实现优化？

工厂HVAC暖通系统如何实现优化？

在工厂运营中&#xff0c;HVAC暖通系统是维持良好生产环境的关键组成部分。然而&#xff0c;由于能效低下&#xff0c;这些系统可能导致昂贵的能源开支&#xff0c;同时对环境造成负担。本文将深入研究工厂HVAC系统的能效低下原因&#xff0c;介绍HVAC系统优化的关键步骤&#…
阅读更多...
老照片模糊不清怎么修复?教你几个修复模糊照片的方法

老照片模糊不清怎么修复?教你几个修复模糊照片的方法

老照片&#xff0c;如同历史的见证者&#xff0c;承载着家族的记忆与故事。它们无声地诉说着我们的成长轨迹&#xff0c;将那些温馨而美好的瞬间永恒定格。然而&#xff0c;岁月无情&#xff0c;这些老照片逐渐变得模糊不清&#xff0c;甚至布满了岁月的痕迹&#xff0c;令我们…
阅读更多...
【第六课课后作业】大模型评测

【第六课课后作业】大模型评测

大模型评测 大模型评测安装环境安装数据准备查看支持的数据集和模型 启动测评评测结果 大模型评测 安装 环境安装 conda create --name opencompass --clone/root/share/conda_envs/internlm-base source activate opencompass git clone https://github.com/open-compass/ope…
阅读更多...
推荐文章
最新文章

Copyright @ 2022~2023