京茶吉鹿_社区达人页_阿里云开发者社区

聊聊接口文档的事儿

1、前言大家好，欢迎来到我的吉鹿（记录）空间。最近在做一个前后端分离的项目时，由于后端提供的 API 接口文档实在是一言难尽，导致了开发的效率大大降低。于是我出手了，我决定薅完我20几年的头发来肝一下接口文档。下面给大家介绍一下，如何正确的在自己的项目中使用接口文档。2、简介2.1、什么是接口文档？接口文档又称为 API 文档，通常由开发人员一起规定的一种规范，一般由后端开发人员所编写的，用来描述系统所提供接口信息的文档。前端人员直接调用某一个接口就可以实现某一个业务流程所需要的数据等信息。2.2、为什么要写接口文档？项目开发过程中前后端开发人员更加方便。项目迭代或者项目人员更迭时，方便后期人员的维护。为测试人员进行接口测试提供便利。3.3、接口文档如何选择？一个合格的接口文档是十分重要的，规范的文档可以很大程度的提高工作效率，尤其是对于接口测试而言。合格的接口文档包含了：项目介绍、业务介绍、环境介绍、项目设计的请求和各个请求方式的传参格式和请求内容以及返回值等。对于一个功能很多的项目来说，接口是非常多的，基本都是上千个，那么为了实现更好的文档管理和阅读的目的，就需要对接口文档根据模块进行划分，不同的模块的划分也有不同的要求。这些都是实现一个合格的接口文档所需要具备的条件。竟然一个接口文档需要花费如此功夫，那么如何编写合格的接口文档呢？手写接口文档？不可能，这辈子都不可能！当然是用 Swagger 接口文档工具了4.4、如何使用Swagger接口文档？废话不多说？走，整点儿东西！到官网去巴拉几下：http://swagger.io ，了解基本用法，如果有看不懂英文的小伙伴，我在下面贴心的为大家准备了 Swagger 基本的模板，下面就简单介绍下 Swagger 基本用法吧。3、Swagger3.1、准备阶段先新建 Spring Boot 工程，然后引入依赖，只需要引入一个版本即可 <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency>  <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-boot-starter</artifactId> <version>3.0.0</version> </dependency>备注：项目使用的 Spring Boot 版本为 2.5.5，如果使用更高版本的 Spring Boot 需要在 application.yml 添加如下配置spring: mvc: path match: matching-strategy: ant_path_matcher3.2、配置 Swagger新建 Swagger2Config.javaSwagger 配置参考：http://springfox.github.io/springfox/docs/current/#quick-start-guides下面的配置方式不仅仅适用于 Swagger 2.9.2 也适用于 Swagger 3.0.0 版本，但是在3.0.0版本中有小部分做了修改，详细体现在代码中的注释处。@Configuration @EnableSwagger2 // 2 // @EnableOpenApi // 3 public class Swagger2Config { @Bean public Docket createRestApi(){ return new Docket(DocumentationType.SWAGGER_2) // 2 // return new Docket(DocumentationType.OAS_30) // 3 .pathMapping("/") .enable(true) .host("localhost:8888") .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.record.controller")) .paths(PathSelectors.any()) .build() .protocols(newHashSet("https","http")) // 2 .securitySchemes(singletonList(apiKey())) .securityContexts(singletonList(securityContext())); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("京茶吉鹿") .description("京茶吉鹿的Demo (SpringBoot2.5.5 + Swagger2.9.2)") .contact(new Contact("京茶吉鹿", "http:localhost:8888/doc.html", "jc.jingchao@qq.com")) .version("1.0.0") .termsOfServiceUrl("http://localhost:8888") .build(); } private ApiKey apiKey(){ return new ApiKey("Authorization", "Authorization", "Header"); } private SecurityContext securityContext(){ return SecurityContext.builder() .securityReferences(defaultAuth()) .forPaths(PathSelectors.regex("/hello/.*")) .build(); } List<SecurityReference> defaultAuth() { AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything"); AuthorizationScope[] authorizationScopes = new AuthorizationScope[1]; authorizationScopes[0] = authorizationScope; return singletonList( new SecurityReference("Authorization", authorizationScopes)); } } 3.3、访问接口文档访问路径：Swagger2.9.2 http://localhost:8888/swagger-ui.htmlSwagger3.0.0 http://localhost:8888/swagger-ui/index.htmlUI 界面如下3.4、使用第三方的UI虽然我们已经实现了Swagger接口文档，但是我们会发现 Swagger 自带的接口文档页面并不是我们喜欢的方式，我们可以使用第三方的界面，只需要引入下面的依赖，使用 http://localhost:8888/doc.html 就可以访问了<dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>swagger-bootstrap-ui</artifactId> <version>1.9.6</version> </dependency>UI 界面如下到此为止，一个完整的接口文档我们已经实现了。原生的 Swagger 就能够满足我们在开发中的使用，尽管我们也使用了第三方的 Swagger UI资源库来美化我们的界面，但是由于 swagger-bootstrap-ui 采用的是后端Java代码 + 前端Ui混合打包的方式，与今天的微服务架构显得格格不入，下面将使用 knife4j 来重新生成接口文档如果你还不想使用 knife4j ，但是你中意与它的外表（UI界面）那么你可以使用引入下面的依赖来替换掉旧版本的 UI<dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>knife4j-spring-ui</artifactId> <version>3.0.3</version> </dependency>UI 界面如下，界面更加美观，神似一个后台管理系统的 UI 界面，同时还可以切换语言，更加值得称赞的是还能进行界面的个性化配置。唯一比较遗憾的是由于你只使用了新版的皮肤，不能体会到接口文档的一些增强特性。看到此处如果 knife4j 仍然不能是你心动，那么你无需再看下面的内容了。4、knife4j4.1、什么是 knife4j？knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案，前身是swagger-bootstrap-ui，取名kni4j是希望她能像一把匕首一样小巧，轻量，并且功能强悍!Knife4j 的主要两点：🆕统一各个组件版本号,使用Knife4j时开发者根据需要自行引用,artifactId发生了变化💯支持Spring Boot 3🌼兼容适配springdoc-openapi底层框架，全面迁移到OpenAPI3的规范支持🌿针对OpenAPI2(Swagger)规范提供了优化，开发者基于Spring Boot2版本可以无缝衔接💪Knife4j-Desktop组件架构升级重写，新架构支持不同需求的OpenAPI规范进行聚合💪提供官方Docker镜像服务，基于Knife4j可方便在云服务上进行使用💥官网文档更新重写Knife4j 架构4.2、为什么使用 knife4j？前后端Java代码以及前端Ui模块进行分离,在微服务架构下使用更加灵活提供专注于Swagger的增强解决方案,不同于只是改善增强前端Ui部分4.3、使用 knife4j下面环境为 SpringBoot 3.0.1 + Knife4j 4.0.0 ，注意项目使用的JDK 版本需要在 17 以上。引入 Knife4j 的 starter<dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId> <version>4.0.0</version> </dependency> 引入Knife4j的 starter后，其余的配置，可以完全参考 springdoc-openapi 的项目说明，Knife4j只提供了增强部分，如果要启用Knife4j的增强功能，可以在配置文件中进行开启# springdoc-openapi项目配置 springdoc: swagger-ui: path: /swagger-ui.html tags-sorter: alpha operations-sorter: alpha api-docs: path: /v3/api-docs group-configs: - group: 'default' paths-to-match: '/**' packages-to-scan: com.xiaominfo.knife4j.demo.web # knife4j的增强配置，不需要增强可以不配 knife4j: enable: true setting: language: zh_cn配置文件@Configuration public class SwaggerConfig { @Bean public GlobalOpenApiCustomizer orderGlobalOpenApiCustomizer() { return openApi -> { if (openApi.getTags()!=null){ openApi.getTags().forEach(tag -> { Map<String,Object> map=new HashMap<>(); map.put("x-order", RandomUtil.randomInt(0,100)); tag.setExtensions(map); }); } if(openApi.getPaths()!=null){ openApi.addExtension("record","1223456"); openApi.getPaths().addExtension("x-record",RandomUtil.randomInt(1,100)); } }; } @Bean public OpenAPI customOpenAPI() { return new OpenAPI().info(new Info() .title("京茶吉鹿系统API") .version("1.0.0") .contact(new Contact().name("京茶吉鹿").email("jc.jingchao@qq.com").url("https://gitee.com/OHUHO")) .description( "Knife4j集成springdoc-openapi示例") .termsOfService("http://localhost:8888") .license(new License().name("Apache 2.0") .url("http://localhost:8888"))); } } 效果预览4.4、使用增强特性Knife4j 新版本已经将UI界面中的个性化配置剥离，只需要在后端进行配置即可。举个栗子，我们现在有这样一个需求，要给接口文档设置一个查看的权限（只有负责这个项目的前端人员才有资格查看），我们就可以为API文档设置密码，需要在配置文件中配置，如下knife4j: # 开启增强配置 enable: true 　# 开启Swagger的Basic认证功能,默认是false basic: enable: true # Basic认证用户名 username: test # Basic认证密码 password: 123到这里我们就学会了如何使用接口文档了。

Hadoop安装教程——单机 / 伪分布式配置

Hadoop3.3.0安装教程本教程最终解释权归作者所有，转载请注明。本教程适合于原生 Hadoop3.3.0，主要参考了《大数据技术原理与应用》第三版，操作步骤详细，相信按照该教程操作，大家都能顺利安装并运行Hadoop。为了方便学习和使用该教程，请读者们利用Linux系统中自带的firefox浏览器打开此教程进行学习。文章目录Hadoop3.3.0安装教程前言一、环境的选择二、创建Hadoop账户三、更新apt四、安装SSH、配置SSH免密码登录五、安装Java环境六、Hadoop3.3.0的安装七、Hadoop单机配置（非分布式）八、Hadoop伪分布式安装1.修改配置文件 core-site.xml2.修改配置文件 hdfs-site.xml3.Hadoop的启动vim使用教程前言随着第三次信息化浪潮的涌动，大数据时代全面到来，人类社会信息科技的发展为大数据的到来提供了技术支持，数据产生方式的变革是促进大数据时代到来的至关重要的因素。大数据已经融入到了我们的生活，为了使我们对大数据有更加深刻的了解，我们大数据的研究刻不容缓。要学习大数据，最基础的就是了解大数据的处理框架Hadoop。Hadoop是一个开源的、可运行于大规模集群上的分布式计算平台，是被公认为行业大数据标准开源软件。几乎所有主流厂商都是以Hadoop为主。一、环境的选择本教程使用Ubtuntu-20.04做为系统环境，当然此教程也适用于Ubtuntu-20.04以下的版本，读者可以根据自己的需要选择相应的版本。若读者如果是选择其他版本（CentOS等）作为系统环境，命令则会有稍微的区别。在安装好Ubtuntu系统后，方可继续进行以下操作。二、创建Hadoop账户如果你安装 Ubuntu 的时候不是用的 “hadoop” 用户，那么需要增加一个名为 hadoop 的用户。首先按 ctrl+alt+t 打开终端窗口，输入如下命令创建新用户 :sudo useradd -m hadoop -s /bin/bash这条命令创建了可以登陆的 hadoop 用户，并使用 /bin/bash 作为 shell。接着使用如下命令设置密码，可简单设置为 hadoop，按提示输入两次密码：sudo passwd hadoop可为 hadoop 用户增加管理员权限，方便部署，避免一些对新手来说比较棘手的权限问题：sudo adduser hadoop sudo最后注销当前用户（点击屏幕右上角的齿轮，选择注销），返回登陆界面。在登陆界面中选择刚创建的 hadoop 用户进行登陆。三、更新apt用 hadoop 用户登录后，我们先更新一下 apt，后续我们使用 apt 安装软件，如果没更新可能有一些软件安装不了。按 ctrl+alt+t 打开终端窗口，执行如下命令：sudo apt-get update由于后续需要更改一些配置文件，我们再此安装vim（当然使用gedit也可）：注：vim的使用请参看教程目录sudo apt-get install vim安装软件时若需要确认，在提示处输入 y 即可。四、安装SSH、配置SSH免密码登录集群、单节点模式都需要用到 SSH 登陆（类似于远程登陆，你可以登录某台 Linux 主机，并且在上面运行命令），Ubuntu 默认已安装了 SSH client，此外还需要安装 SSH server：sudo apt-get install openssh-server安装后，可以使用如下命令登陆本机：ssh localhost此时会有如下提示(SSH首次登陆提示)，输入 yes 。然后按提示输入密码 hadoop，这样就登陆到本机了。但这样登陆是需要每次输入密码的，我们需要配置成SSH无密码登陆比较方便。首先退出刚才的 ssh，就回到了我们原先的终端窗口，然后利用 ssh-keygen 生成密钥，并将密钥加入到授权中：exit # 退出刚才的 ssh localhost cd ~/.ssh/ # 若没有该目录，请先执行一次ssh localhost ssh-keygen -t rsa # 会有提示，都按回车就可以 cat ./id_rsa.pub >> ./authorized_keys # 加入授权 ———————————————— 版权声明：本文为CSDN博主「京茶吉鹿」的原创文章，遵循CC 4.0 BY-SA版权协议，转载请附上原文出处链接及本声明。原文链接：https://blog.csdn.net/weixin_52372879/article/details/120383395此时再用 ssh localhost 命令，无需输入密码就可以直接登陆了，如下图所示。五、安装Java环境Hadoop3.3.0需要使用JDK版本在1.8以上，读者需要按下面的步骤安装JDK1.8。读者需使用Ubtuntu自带的火狐浏览器打开Java官网，切记不要使用本地浏览器下载（如果使用本地浏览器下载需要使用WinSCP使用传送至虚拟机中）。打开网址我们选择下载 jdk-8u-301-linux-x64.tar.gz（即最后一项下载）。在Linux命令行界面中，执行如下Shell命令（注意：当前登录用户名是hadoop）：cd /usr/lib sudo mkdir jvm #创建/usr/lib/jvm目录用来存放JDK文件 cd ~ #进入hadoop用户的主目录 cd 下载 #jdk压缩包默认下载在该位置 sudo tar -zxvf ./jdk-8u301-linux-x64.tar.gz -C /usr/lib/jvm #把JDK文件解压到/usr/lib/jvm目录下JDK文件解压缩以后，可以执行如下命令到/usr/lib/jvm目录查看一下：cd /usr/lib/jvm ls可以看到，在/usr/lib/jvm目录下有个jdk1.8.0_301目录。下面继续执行如下命令，设置环境变量：cd ~ vim ~/.bashrc上面命令使用vim编辑器（注：vim的使用请参看教程目录）打开了hadoop这个用户的环境变量配置文件，请在这个文件的开头位置，添加如下几行内容：export JAVA_HOME=/usr/lib/jvm/jdk1.8.0_301 export JRE_HOME=${JAVA_HOME}/jre export CLASSPATH=.:${JAVA_HOME}/lib:${JRE_HOME}/lib export PATH=${JAVA_HOME}/bin:$PATH保存.bashrc文件并退出vim编辑器。然后，继续执行如下命令让.bashrc文件的配置立即生效：source ~/.bashrc这时，可以使用如下命令查看是否安装成功：java -version如果能够在屏如果能够在屏幕上返回如下信息，则说明安装成功：至此，成功安装了Java环境，下面就可以安装Hadoop了。六、Hadoop3.3.0的安装同样，我们选择到Hadoop官网下载hadoop-3.3.0.tar.gz。读者还是需要在Ubtunbu中自带的浏览器中下载。直接下载第一项即可。我们选择将 Hadoop 安装至 /usr/local/ 中：cd ~ #进入hadoop用户的主目录 cd 下载 #jdk压缩包默认下载在该位置 sudo tar -zxf ~/下载/hadoop-3.3.0.tar.gz -C /usr/local # 解压到/usr/local中 cd /usr/local/ sudo mv ./hadoop-3.3.0/ ./hadoop # 将文件夹名改为hadoop sudo chown -R hadoop ./hadoop # 修改文件权限Hadoop 解压后即可使用。输入如下命令来检查 Hadoop 是否可用，成功则会显示 Hadoop 版本信息：cd /usr/local/hadoop ./bin/hadoop version七、Hadoop单机配置（非分布式）Hadoop 默认模式为非分布式模式（本地模式），无需进行其他配置即可运行。非分布式即单 Java 进程，方便进行调试。现在我们可以执行例子来感受下 Hadoop 的运行。Hadoop 附带了丰富的例子（运行 ./bin/hadoop jar ./share/hadoop/mapreduce/hadoop-mapreduce-examples-3.3.0.jar 可以看到所有例子），包括 wordcount、terasort、join、grep 等。在此我们选择运行 grep 例子，我们将 input 文件夹中的所有文件作为输入，筛选当中符合正则表达式 dfs[a-z.]+ 的单词并统计出现的次数，最后输出结果到 output 文件夹中。cd /usr/local/hadoop mkdir ./input cp ./etc/hadoop/*.xml ./input # 将配置文件作为输入文件 ./bin/hadoop jar ./share/hadoop/mapreduce/hadoop-mapreduce-examples-3.3.0.jar grep ./input ./output 'dfs[a-z.]+' cat ./output/* # 查看运行结果执行成功后如下所示，输出了作业的相关信息，输出的结果是符合正则的单词 dfsadmin 出现了1次注意：Hadoop 默认不会覆盖结果文件，因此再次运行上面实例会提示出错，需要先将 ./output 删除。rm -r ./output八、Hadoop伪分布式安装Hadoop 可以在单节点上以伪分布式的方式运行，Hadoop 进程以分离的 Java 进程来运行，节点既作为 NameNode 也作为 DataNode，同时，读取的是 HDFS 中的文件。Hadoop 的配置文件位于 /usr/local/hadoop/etc/hadoop/ 中，伪分布式需要修改2个配置文件 core-site.xml 和 hdfs-site.xml 。Hadoop的配置文件是 xml 格式，每个配置以声明 property 的 name 和 value 的方式来实现。1.修改配置文件 core-site.xml使用下面的命令（注：vim的使用请参看教程目录）cd /usr/local/hadoop/etc/hadoop/ vim core-site.xml修改配置文件 core-site.xml ，将当中的<configuration> </configuration>修改为下面配置：<configuration> <property> <name>hadoop.tmp.dir</name> <value>file:/usr/local/hadoop/tmp</value> <description>Abase for other temporary directories.</description> </property> <property> <name>fs.defaultFS</name> <value>hdfs://localhost:9000</value> </property> </configuration>2.修改配置文件 hdfs-site.xml使用下面的命令：vim hdfs-site.xml修改配置文件 hdfs-site.xml<configuration> <property> <name>dfs.replication</name> <value>1</value> </property> <property> <name>dfs.namenode.name.dir</name> <value>file:/usr/local/hadoop/tmp/dfs/name</value> </property> <property> <name>dfs.datanode.data.dir</name> <value>file:/usr/local/hadoop/tmp/dfs/data</value> </property> </configuration>3.Hadoop的启动配置完成后，执行 NameNode 的格式化:cd /usr/local/hadoop ./bin/hdfs namenode -format成功的话，会返回很多行非常长的提示信息。接着开启 NameNode 和 DataNode 守护进程。cd /usr/local/hadoop ./sbin/start-dfs.sh #启动Hadoop若出现SSH提示信息，输入yes即可。启动时可能会出现WARN 提示，可以忽略WARN 提示，并不会影响正常使用。成功启动后，可以访问 Web 界面 http://localhost:9870 查看 NameNode 和 Datanode 信息，还可以在线查看 HDFS 中的文件。如下图所示：关闭Hadoop，则运行：./sbin/stop-dfs.sh注意：当下次启动 hadoop 时，无需再进行 NameNode 的初始化，只需要运行 ./sbin/start-dfs.sh 就可以！vim使用教程说明：以下vim使用方法只是在该教程用到的，如想了解更多，请参考菜鸟教程i 切换到输入模式，以输入字符。: 切换到底线命令模式，以在最底一行输入命令。ESC，退出输入模式，切换到命令模式。q 退出程序。w 保存文件。备注：在vim编辑文档时，输入 i 以输入字符；写入文档后，按 Esc 键，输入 :wq 以退出和保存文件。