跨語言跨平臺聚合 OpenAPI 文檔歷來沒有這麼簡單過

時間  2020-11-30
標籤 html java git github web spring docker shell apache json 欄目 設計模式 简体版
原文   原文鏈接

Knife4j一直致力於將目前的Ui提供給更多的平臺或者別的語言使用而努力，通過這麼長時間的發展，Knife4j提供的輕量級聚合中間件終於誕生了，自2.0.8版本開始，Knife4j提供了knife4j-aggregation-spring-boot-starter組件，該組件是一個基於Spring Boot系統的starter，他提供瞭如下幾種能力：html

  • 最輕量級、最簡單、最方便的聚合OpenApi規範的中間件
  • 讓全部的基於Spring Boot的Web體系擁有了輕鬆聚合OpenApi的能力
  • 提供4種模式供開發者選擇
    • 基於本地靜態JSON文件的方式聚合OpenAPI
    • 基於雲端HTTP接口的方式聚合
    • 基於Eureka註冊中心的方式聚合
    • 基於Nacos註冊中心的方式聚合
  • 基於該starter發佈了Docker鏡像，跨平臺與語言讓開發者基於此Docker鏡像輕鬆進行聚合OpenAPI規範
  • 完美兼容全部Spring Boot版本，沒有兼容性問題
  • 開發者能夠完全放棄基於Zuul、Spring Cloud Gateway等複雜的聚合方式
  • 兼容OpenAPI2規範以及OpenAPI3規範

本文主要介紹5種模式來使用Knife4j提供的聚合組件進行OpenAPI文檔的聚合java

  • Disk本地文件模式
  • Cloud雲端接口模式
  • Eureka註冊中心
  • Nacos註冊中心
  • Docker鏡像跨語言

Disk模式

基於Disk模式聚合是最簡單的，開發者只須要在Spring Boot的項目中存在OpenAPI規範的JSON文件便可進行聚合git

完整代碼請參考knife4j-aggregation-disk-demogithub

主要步驟以下：web

一、建立Spring Boot項目，引入Knife4jAggregation的依賴包，完整pom文件以下：spring

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.4.0</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-aggregation-disk-demo</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>knife4j-aggregation-disk-demo</name>
    <description>經過基於Spring Boot的工程聚合任意微服務接口文檔</description>

    <properties>
        <java.version>1.8</java.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-aggregation-spring-boot-starter</artifactId>
            <version>2.0.8</version>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>

</project>

二、配置yml配置文件，以下：docker

server:
  port: 19081
knife4j:
  enableAggregation: true
  disk:
    enable: true
    routes:
      - name: 用戶
        location: classpath:openapi/user.json

工程目錄以下圖：shell

三、啓動項目，訪問doc.html進行查看，效果圖以下apache

Cloud模式聚合OpenAPI文檔

Cloud(雲端)模式和Disk模式大同小異，主要的區別是獲取OpenAPI規範的方式換成了基於HTTP接口而已json

完整代碼請參考knife4j-aggregation-cloud-demo

本次Cloud聚合以Knife4j目前部署的線上demo爲例，本地聚合在線的OpenAPI，而且能夠本地調試，Knife4jAggregation組件會自動幫助咱們轉發

任意取目前Knife4j的線上demo兩個OpenAPI規範接口地址：

主要步驟以下：

一、建立Spring Boot項目，引入Knife4jAggregation的依賴包，完整pom文件以下：

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.4.0</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-aggregation-disk-demo</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>knife4j-aggregation-disk-demo</name>
    <description>經過基於Spring Boot的工程聚合任意微服務接口文檔</description>

    <properties>
        <java.version>1.8</java.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-aggregation-spring-boot-starter</artifactId>
            <version>2.0.8</version>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>

</project>

二、配置yml配置文件，以下：

server:
  port: 19081
knife4j:
  enableAggregation: true
  cloud:
    enable: true
    routes:
      - name: 測試分組1
        uri: knife4j.xiaominfo.com
        location: /v2/api-docs?group=2.X版本
      - name: 測試分組2
        uri: knife4j.xiaominfo.com
        location: /v2/api-docs?group=3.默認接口

三、啓動項目，訪問doc.html進行查看，效果圖以下：

聚合效果：

在線調試：

Eureka註冊中心聚合OpenAPI文檔

從Eureka註冊中心進行聚合的模式和Cloud模式大同小異，主要的區別是經過serviceName來替代了真實的目標服務地址，而是從Eureka註冊中心進行動態獲取

完整代碼請參考knife4j-aggregation-eureka-demo

先來看整個工程的目錄：

工程目錄說明以下： |工程|說明| |--|---| |service-server|Eureka註冊中心| |service-user|一個很是簡單的用戶服務，包含用戶接口| |service-order|一個很是簡單的訂單服務，包含訂單接口| |service-doc|聚合文檔工程，也是一個Spring Boot工程，不過須要注意的是基於web的，而非webflux|

Eureka註冊中心以及service-user、order等都很是簡單，按照註冊中心、用戶服務、訂單服務依次進行啓動便可

此時，咱們訪問Eureka的主頁，最終能看到咱們的註冊中心存在兩個服務，以下圖：

那麼，咱們的目標是什麼呢？從Eureka註冊中心直接進行聚合，也就是將用戶服務、訂單服務的OpenAPI文檔聚合在一塊兒進行展現

主要步驟以下：

一、在service-doc工程引入knife4j-aggregation-spring-boot-starter依賴

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>com.xiaominfo.swagger</groupId>
        <artifactId>knife4j-aggregation-eureka-demo</artifactId>
        <version>1.0</version>
        <relativePath>../pom.xml</relativePath> <!-- lookup parent from repository -->
    </parent>
    <groupId>com.xiaominfo.swagger</groupId>
    <artifactId>service-doc</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>service-doc</name>
    <description>Eureka聚合</description>

    <properties>
        <java.version>1.8</java.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-aggregation-spring-boot-starter</artifactId>
            <version>2.0.8</version>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>

</project>

二、配置yml配置文件，以下：

server:
  port: 10909
knife4j:
  enableAggregation: true
  eureka:
    enable: true
    serviceUrl: http://localhost:10000/eureka/
    routes:
      - name: 訂單服務
        serviceName: service-order
        location: /v2/api-docs?group=default
        servicePath: /order
      - name: 用戶體系
        serviceName: service-user
        location: /aub/v2/api-docs?group=default
        servicePath: /

三、啓動項目，訪問doc.html進行查看，效果圖以下：

聚合效果：

在線調試：

只須要簡單的配置，就輕鬆的將Eureka註冊中心的各個服務進行了聚合，是否是比Spring Cloud Gateway、Zuul更加簡單和輕量呢？

關於Eureka的更多配置須要開發者參考文檔

Nacos註冊中心聚合OpenAPI文檔

Nacos的配置和Eureka幾乎如出一轍，惟一不一樣的區別是在yml進行配置的時候，使用的是knife4j.nacos開頭，其餘基本都是同樣

關於Nacos的更多配置須要開發者參考文檔

基於Knife4j的Docker鏡像快速聚合OpenAPI

在前面的實戰文章中，更多的是面向Java開發者，經過Spring Boot框架，快速聚合OpenAPI文檔。

那麼其餘語言可否也能這麼方便的使用Knife4j呢？

答案是確定的，Knife4j爲了讓其餘語言很是方便的使用Knife4j來渲染聚合OpenAPI文檔，在DockerHub中推送了Knife4j的鏡像，

鏡像地址：https://hub.docker.com/repository/docker/xiaoymin/knife4j

若是你的本機或者服務器安裝了Docker，那麼利用Knife4j的鏡像來聚合OpenAPI將會很是方便

首先須要將鏡像從DockerHub拉到本地，命令以下：

docker pull xiaoymin/knife4j:latest

若是pull速度比較慢的話，開發者能夠配置鏡像源 ::: details /etc/docker/daemon.json

{
  "registry-mirrors": [
    "https://registry.docker-cn.com",
    "http://hub-mirror.c.163.com",
    "https://3laho3y3.mirror.aliyuncs.com",
    "https://mirror.ccs.tencentyun.com"
  ]
}

::: 鏡像下載到本地機器後，下面將詳細介紹如何經過Knife4j的鏡像實現上面文章介紹的4中不一樣方式的聚合OpenAPI文檔

鏡像說明

Knife4j的鏡像是一個基於Spring Boot框架開發的Web項目，對外默認端口8888

源碼地址：https://gitee.com/xiaoym/knife4j/tree/v2/knife4j-aggregation-docker

FROM openjdk:8-jdk-alpine
LABEL version="2.0"
LABEL released-date=2020/11/25
LABEL author="xiaoymin@foxmail.com"
LABEL description="Knife4jAggregation OpenAPI,RunAnyWhere!!!"
MAINTAINER xiaoymin
RUN mkdir /app
# Disk模式數據掛載目錄
RUN mkdir /app/data
ADD src/main/resources/application.yml /app/app.yml
ADD target/knife4j-aggregation-docker-1.0.jar /app/app.jar
ENTRYPOINT ["java","-jar","-Djava.security.egd=file:/dev/./urandom","-Duser.timezone=Asia/Shanghai","/app/app.jar","--spring.config.location=/app/app.yml"]
#EXPOSE 8888:

從Knife4j的Dockerfile文件中，咱們能夠看到爲Knife4j的應用建立了一個/app目錄和/app/data目錄，用來存放jar文件和yml配置文件，該目錄是經過外部文件與Docker容器進行掛載關聯的關鍵。

Disk模式

Disk模式主要是從本地聚合OpenAPI規範，那麼如何利用Knife4j的容器進行渲染呢？這裏就要用到咱們剛剛上面說的文件掛載

第一步：在服務器(宿主機)上建立相關目錄，例如：/home/openapi

咱們在該目錄下主要存放兩種類型的文件目錄，1種是Knife4j鏡像文件須要的yml配置文件，第二種是存放OpenAPI的規範JSON,目錄結構以下：

[root@izbpc3 openapi]# pwd
/home/openapi
[root@izbpc3 openapi]# ll
total 8
-rw-r--r-- 1 root root  241 Nov 25 19:42 app.yml
drwxr-xr-x 2 root root 4096 Nov 25 19:41 data
[root@izbpc3 openapi]# cd data
[root@izbpc3 data]# ll
total 256
-rw-r--r-- 1 root root  21448 Nov 25 19:41 open-api.json
-rw-r--r-- 1 root root 237303 Nov 25 19:41 openapi.json

Disk模式咱們主要須要作的是修改app.yml配置文件中的配置，指定Knife4j的鏡像從本地加載指定的openapi.json，經過界面顯示

app.yml配置修改以下：

server:
  port: 8888
knife4j:
  enableAggregation: true
  disk:
    enable: true
    routes:
      - name: 用戶AAAAAAAAAAA
        location: /app/data/open-api.json
      - name: 用戶BBBBBBBBBBBB
        location: /app/data/openapi.json

這裏須要注意的是

一、location咱們使用的是容器的目錄/app,咱們最終建立容器的時候會將宿主機的目錄(/home/openapi/data)掛載給容器，達到文件共享的目的

二、在app.yml配置中指定的端口是容器的端口，Knife4j默認端口8888，若是開發者使用該配置而且修改了端口，那麼須要在端口映射的時候也相應的進行修改

第二步：啓動Knife4j容器查看效果

經過Docker命令建立容器，命令以下：

[root@izbx23 app]# docker run -itd --name myopenapi -p 18002:8888 -v /home/openapi/app.yml:/app/app.yml -v /home/openapi/data:/app/data xiaoymin/knife4j
3f0ed4cde46dd8a625e0338bc8cb1688059c7169447bda5681a34d93e2ba7c3e
[root@izbx23 app]# docker ps 
CONTAINER ID        IMAGE               COMMAND                  CREATED             STATUS              PORTS                     NAMES
e678bccd4d66        xiaoymin/knife4j    "java -jar -Djava.se…"   3 seconds ago       Up 2 seconds        0.0.0.0:18002->8888/tcp   myopenapi
  • --name命令是指定一個別名
  • -p表明端口映射 18002是宿主機端口號，8888是容器的端口號，
  • -v參數則是將本地目錄掛載和容器共享,此處主要掛載兩個文件，一個是app.yml配置文件，一個是openapi.json文件

此時，咱們經過端口號進行訪問：http://localhost:18002/doc.html

效果圖以下：

容器建立成功後，咱們能夠訪問容器的文件系統，經過命令以下：

[root@izbx23 conf.d]# docker exec -it myopenapi sh
/ # ls
app    bin    dev    etc    home   lib    media  mnt    opt    proc   root   run    sbin   srv    sys    tmp    usr    var
/ # cd app
/app # ls
app.jar  app.yml  data
/app # cd data
/app/data # ls
open-api.json  openapi.json
/app/data #

咱們在容器中的文件系統中/app/data目錄中，其實能夠看到，這個目錄中的文件和咱們經過建立容器時-v參數掛載的目錄文件是一致的。

Cloud模式

Cloud模式就相對簡單多了，咱們只須要修改當前的app.yml配置文件便可，而後建立容器時進行覆蓋便可

任意取目前Knife4j的線上demo兩個OpenAPI規範接口地址：

配置yml配置文件，以下：

server:
  port: 8888
knife4j:
  enableAggregation: true
  cloud:
    enable: true
    routes:
      - name: cloud1
        uri: knife4j.xiaominfo.com
        location: /v2/api-docs?group=2.X版本
      - name: cloud2
        uri: knife4j.xiaominfo.com
        location: /v2/api-docs?group=3.默認接口

經過Docker命令建立容器，命令以下：

[root@izbx23 openapi]# docker run -itd --name cloudapi -p 18002:8888 -v /home/openapi/app.yml:/app/app.yml xiaoymin/knife4j
6b81844e0c605704eef3ffcb207e090a1139a9fbc8dcf0a43efdcb60f41d327c
[root@izbx23 openapi]# docker ps
CONTAINER ID        IMAGE               COMMAND                  CREATED             STATUS              PORTS                     NAMES
6b81844e0c60        xiaoymin/knife4j    "java -jar -Djava.se…"   4 seconds ago       Up 3 seconds        0.0.0.0:18002->8888/tcp   cloudapi
  • --name命令是指定一個別名(cloudapi)
  • -p表明端口映射 18002是宿主機端口號，8888是容器的端口號，
  • -v參數則是將本地目錄掛載和容器共享,此處只須要覆蓋app.yml配置文件便可，由於咱們的OpenAPI數據來源於HTTP接口

此時，咱們經過端口號進行訪問：http://localhost:18002/doc.html

效果圖以下：

註冊中心(Eureka && Nacos)

至於從註冊中心(Eureka && Nacos)進行OpenAPI的聚合和Cloud模式下同樣，開發者只須要修改app.yml配置文件，而後經過-v參數進行掛載覆蓋文件便可。更多的配置須要參考聚合組件的文檔參數詳細介紹文檔

相關文章
相關標籤/搜索
每日一句
    每一个你不满意的现在，都有一个你没有努力的曾经。
本站公眾號
   歡迎關注本站公眾號,獲取更多信息
聯繫我們 最近搜索 最新文章 沪ICP备13005482号-10 MyBatis教程 SQL 教程 MySQL教程 Java 教程 Thymeleaf 教程 Hibernate教程 Spring教程 Redis教程