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

文章目录

  • 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开放平台目录结构：

在这里插入图片描述

在这里插入图片描述

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

如若内容造成侵权/违法违规/事实不符，请联系我们进行投诉反馈qq邮箱809451989@qq.com，一经查实，立即删除！

相关文章

jar手动上传到Nexus私服

jar手动上传到Nexus私服

jar手动上传到Nexus私服 一简介二上传方法1.登录nexus,打开nexus控制台。upload---maven-release2.上传jar3.验证jar包是否上传成功4、注意事项 一简介 在maven项目中我们可以通过相关配置可以将项目打包成jar&#xff0c;然后deploy上传到私服中。要是别人提供的第三方jar&am…
阅读更多...
HCIA-HarmonyOS设备开发认证-2.设备开发入门

HCIA-HarmonyOS设备开发认证-2.设备开发入门

目录 HarmonyOS设备开发学习路径一、开发项目与工具介绍1.1、设备开发环境准备1.2、设备开发流程1.3、Huawei DevEco Device Tool 二、OpenHarmony介绍OpenHarmony目录结构详细介绍 待续... HarmonyOS设备开发学习路径 一、开发项目与工具介绍 1.1、设备开发环境准备 Window、…
阅读更多...
【python题解17】给你一个有符号整数x，返回将x中的数字部分反转后的结果。输入的整数不超过int类型的最大范围。

【python题解17】给你一个有符号整数x，返回将x中的数字部分反转后的结果。输入的整数不超过int类型的最大范围。

1. 题目&#xff1a;给你一个有符号整数x&#xff0c;返回将x中的数字部分反转后的结果。输入的整数不超过int类型的最大范围。 输入样例&#xff1a;-123 输出样例&#xff1a;-321 2. 源代码 n int(input()) flag True #代表正数 if n < 0: #当n是负数时候&#xff…
阅读更多...
大数据开发之Spark（spark streaming）

大数据开发之Spark（spark streaming）

第 1 章&#xff1a;SparkStreaming概述 1.1 spark streaming是什么 spark streaming用于流式数据的处理。 spark streaming支持的数据源很多&#xff0c;例如&#xff1a;kafka、flume、hdfs等。 数据输入后可以用spark的高度抽象原语如&#xff1a;map、reduce、join、wind…
阅读更多...
Unity配置表xlsx/xls打包后读取错误问题

Unity配置表xlsx/xls打包后读取错误问题

前言 代码如下&#xff1a; //文本解析private void ParseText(){//打开文本 读FileStream stream File.Open(Application.streamingAssetsPath excelname, FileMode.Open, FileAccess.Read, FileShare.Read);//读取文件流IExcelDataReader excelRead ExcelReaderFactory…
阅读更多...
Flume1.9基础学习

Flume1.9基础学习

文章目录 一、Flume 入门概述1、概述2、Flume 基础架构2.1 Agent2.2 Source2.3 Sink2.4 Channel2.5 Event 3、Flume 安装部署3.1 安装地址3.2 安装部署 二、Flume 入门案例1、监控端口数据官方案例1.1 概述1.2 实现步骤 2、实时监控单个追加文件2.1 概述2.2 实现步骤 3、实时监…
阅读更多...
ElasticSearch搜索引擎入门到精通

ElasticSearch搜索引擎入门到精通

ES 是基于 Lucene 的全文检索引擎，它会对数据进行分词后保存索引，擅长管理大量的数据，相对于 MySQL 来说不擅长经常更新数据及关联查询。这篇文章就是为了进一步了解一下它，到底是如何做到这么高效的查询的。 在学习其他数据库的时候我们知道索引是一个数据库系统极其重要…
阅读更多...
OpenAI正式推出GPT商店 ChatGPT团队订阅服务一并推出

OpenAI正式推出GPT商店 ChatGPT团队订阅服务一并推出

2024年1月11日消息&#xff0c;据外媒报道&#xff0c;如上周在给开发者的邮件中所宣布的一样&#xff0c;因ChatGPT而名声大噪的人工智能公司OpenAI&#xff0c;在本周正式推出了GPT商店&#xff0c;供用户分享和发现个性化的ChatGPT&#xff0c;同时他们也推出了面向各种不同…
阅读更多...
【Java 数据结构】ArrayList与顺序表

【Java 数据结构】ArrayList与顺序表

ArrayList 1.线性表2.顺序表2.1 接口的实现 3. ArrayList简介4. ArrayList使用4.1 ArrayList的构造4.2 ArrayList常见操作4.3 ArrayList的遍历4.4 ArrayList的扩容机制 1.线性表 线性表&#xff08;linear list&#xff09;是n个具有相同特性的数据元素的有限序列。 线性表是一…
阅读更多...
Java / Spring Boot + POI 给 Word 添加水印

Java / Spring Boot + POI 给 Word 添加水印

1、前言(瞎扯) 事情是这样子的&#xff1a;我好哥们所在的公司实在是太忙了&#xff0c;多线程都开起来了还是忙不完&#xff0c;只能开了子线程叫我帮他整一个给 Word 加水印的&#xff0c;于是我就网上找呗~ 看到那个 Aspose 好像是收费的&#xff0c;然后就把目光转向了 POI…
阅读更多...
基于物联网设计的水稻田智能灌溉系统(STM32+华为云IOT)

基于物联网设计的水稻田智能灌溉系统(STM32+华为云IOT)

一、项目介绍 随着科技的不断发展和人们生活水平的提高&#xff0c;农业生产也逐渐向智能化、高效化的方向发展。水稻作为我国主要的粮食作物之一&#xff0c;其生长过程中的灌溉管理尤为重要。传统的灌溉方式往往依赖于人工观察和控制&#xff0c;不仅效率低下&#xff0c;而…
阅读更多...
城市开发区视频系统建设方案：打造视频基座、加强图像数据治理

城市开发区视频系统建设方案：打造视频基座、加强图像数据治理

一、背景需求 随着城市建设的步伐日益加快&#xff0c;开发区已经成为了我国工业化、城镇化和对外开放的重要载体。自贸区、开发区和产业园的管理工作自然也变得至关重要。在城市经开区的展览展示馆、进出口商品展示交易中心等地&#xff0c;数千路监控摄像头遍布各角落&#…
阅读更多...
Spring-Kafka 3.0 消费者消费失败处理方案

Spring-Kafka 3.0 消费者消费失败处理方案

一、背景 我们作为Kafka在使用Kafka是&#xff0c;必然考虑消息消费失败的重试次数&#xff0c;重试后仍然失败如何处理&#xff0c;要么阻塞&#xff0c;要么丢弃&#xff0c;或者保存 二、设置消费失败重试次数 1 默认重试次数在哪里看 Kafka3.0 版本默认失败重试次数为1…
阅读更多...
27.移除元素（力扣LeetCode）

27.移除元素（力扣LeetCode）

文章目录 27.移除元素&#xff08;力扣LeetCode&#xff09;题目描述方法一&#xff1a;vector成员函数&#xff1a;erase方法二&#xff1a;暴力解法方法三&#xff1a;双指针法 27.移除元素&#xff08;力扣LeetCode&#xff09; 题目描述 给你一个数组 nums 和一个值 val&…
阅读更多...
【开源】基于JAVA语言的班级考勤管理系统

【开源】基于JAVA语言的班级考勤管理系统

目录 一、摘要1.1 项目介绍1.2 项目录屏 二、功能模块2.1 系统基础支持模块2.2 班级学生教师支持模块2.3 考勤签到管理2.4 学生请假管理 三、系统设计3.1 功能设计3.1.1 系统基础支持模块3.1.2 班级学生教师档案模块3.1.3 考勤签到管理模块3.1.4 学生请假管理模块 3.2 数据库设…
阅读更多...
python Django入门

python Django入门

1.创建Django项目 方式一:进入到指定要存放项目的目录&#xff0c;执行*django-admin startproject “projectname”* 来创建一个名方式二:使用Pycharm专业版创建Django项目 创建项目后&#xff0c;默认的目录结构: manage.py:是Django用于管理本项目的命令行工具&#xff0c…
阅读更多...
前出深入-机器学习

前出深入-机器学习

文章目录 一、K近邻算法1.1 先画一个散列图1.2 使用K最近算法建模拟合数据1.3 进行预测1.4 K最近邻算法处理多元分类问题1.5 K最近邻算法用于回归分析1.6 K最近邻算法项目实战-酒的分类1.6.1 对数据进行分析1.6.2 生成训练数据集和测试数据集1.6.3 使用K最近邻算法对数据进行建…
阅读更多...
如何在Shopee平台上进行选品 ：充分利用渠道获取灵感和数据支持

如何在Shopee平台上进行选品 ：充分利用渠道获取灵感和数据支持

在Shopee平台上进行选品是一个关键的决策过程&#xff0c;它直接影响到卖家的销售业绩和店铺的发展。为了帮助卖家更好地进行选品&#xff0c;Shopee提供了多种渠道来获取灵感和数据支持。下面将介绍一些主要的选品渠道以及如何利用它们来进行选品。 先给大家推荐一款shopee知…
阅读更多...
【DDD】学习笔记-深入分析软件的复杂度

【DDD】学习笔记-深入分析软件的复杂度

软件复杂度的成因 Eric Evans 的经典著作《领域驱动设计》的副标题为“软件核心复杂性应对之道”&#xff0c;这说明了 Eric 对领域驱动设计的定位就是应对软件开发的复杂度。Eric 甚至认为&#xff1a;“领域驱动设计只有应用在大型项目上才能产生最大的收益”。他通过 Smart…
阅读更多...
C#，数据检索算法之线性检索（Linear Search）的源代码

C#，数据检索算法之线性检索（Linear Search）的源代码

数据检索算法是指从数据集合&#xff08;数组、表、哈希表等&#xff09;中检索指定的数据项。 数据检索算法是所有算法的基础算法之一。 线性&#xff1f;听起来就“高大上”&#xff0c;其实&#xff0c;只不过就是挨个比较呗。 本文发布&#xff08;听起来很正式 &#x…
阅读更多...
最新文章

Copyright @ 2022~2023