练手项目2笔记之day01

文章目录

学习目标
1. 项目的功能架构
- 1. 项目背景
- 2. 功能模块
- 3. 项目原型
2. 项目的技术架构
- 1. 技术架构
- 2. 技术栈
- 3. 开发步骤
3. CMS需求分析
- 1. 什么是CMS
- 2. 静态门户工程搭建
- - 1. 导入门户工程
  - 2. 配置虚拟主机
- 3. SSI服务端包含技术
- 3. CMS页面管理需求
4. CMS服务端工程搭建
- 1. 开发工具配置
- 2. 导入基础工程
- - 1. 工程结构
- 4. 导入CMS数据库
5. 页面查询接口定义
- 1. 定义模型
- - 1. 需求分析
  - 2. 模型类介绍
- 2. 定义接口
- - 1. 定义请求和响应类型
  - 2. 定义接口
6. 页面查询服务端开发
- 1. 创建CMS服务工程
- - 1. 创建CMS工程结构
  - 2. 测试Controller
- 2. Dao
- - 1. 分页查询测试
  - - 1. 定义dao接口
    - 2. 编写测试类
  - 2. 基础方法测试
  - 3. 自定义dao方法
- 3. service
- 4. Controller
7. 页面查询接口测试
- 1. Swagger
- - 1. 介绍
  - 2. Swagger常用注解
  - 3. Swagger接口定义
  - 4. 测试
- 2. Postman

学习目标

了解项目的功能架构
理解项目的技术架构
能够说出CMS的功能需求
能够搭建CMS服务端工程
能够定义CMS页面列表接口
能够完成CMS页面列表接口开发
能够完成页面列表接口的测试

1. 项目的功能架构

1. 项目背景

在线教育市场按照市场领域细分为：学前教
育、K12教育、高等教育、留学教育、职业教育、语言教育、兴趣教育以及综合平台，其中，职业教育和语言教育的市场优势突出。未来三年互联网教育市场规模保持高速增长。

学成在线借鉴了MOOC（大型开放式网络课程，即MOOC（massive open online courses））的设计思想，是一个提供IT职业课程在线学习的平台，它为即将和已经加入IT领域的技术人才提供在线学习服务，用户通过在线学习、在线练习、在线考试等学习内容，最终掌握所学的IT技能，并能在工作中熟练应用。

2. 功能模块

学成在线采用B2B2C业务模式，即向企业或个人提供在线教育平台提供教学服务，老师和学生通过平台完成整个教学和学习的过程，市场上类似的平台有：网易云课堂、腾讯课堂等，学成在线的特点是IT职业课程在线教学。

学成在线包括门户、学习中心、教学管理中、社交系统、系统管理等功能模块。

功能模块名称	功能说明
门户	在首页、活动页、专题页等页面提供课程学习入口。
学习中心	学生登录学习中心在线学习课程。
社交系统	社交系统为老师和学生交流搭建沟通的平台，包括：问答系统、评论系统、论坛等，学生和老师通过问答系统提问问题、回答问题，通过评论系统对老师授课进行评论。
教学管理中心	教师登录教学管理中心进行课程管理、资源管理、考试管理等教学活动。
系统管理中心	系统管理员登录系统管理中心进行分类管理、运维管理等功能。

3. 项目原型

博学谷

2. 项目的技术架构

1. 技术架构

采用前后端分离的技术架构，由用户层、UI层、微服务层、数据层等部分组成，为PC、App、
H5等客户端用户提供服务。下图是系统的技术架构图：

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-37ITRfop-1634463146408)(img\dya0102.png)]

业务流程举例：
1、用户可以通过pc、手机等客户端访问系统进行在线学习。
2、系统应用CDN技术，对一些图片、CSS、视频等资源从CDN调度访问。
3、所有的请求全部经过负载均衡器。
4、对于PC、H5等客户端请求，首先请求UI层，渲染用户界面。
5、客户端UI请求服务层获取进行具体的业务操作。
6、服务层将数据持久化到数据库

各模块的说明如下：

序号	名称	功能描述
1	用户层	用户层描述了本系统所支持的用户类型包括：pc用户、app用户、h5用户。pc用户通过浏览器访问系统、app用户通过android、ios手机访问系统，H5用户通过h5页面访问系统。
2	CDN	CDN全称Content Delivery Network，即内容分发网络，本系统所有静态资源全部通过CDN加速来提高访问速度。系统静态资源包括：html页面、js文件、css文件、image图片、pdf和ppt及doc教学文档、video视频等
3	负载均衡	系统的CDN层、UI层、服务层及数据层均设置了负载均衡服务，上图仅在UI层前边标注了负载均衡。每一层的负载均衡会根据系统的需求来确定负载均衡器的类型，系统支持4层负载均衡+7层负载均衡结合的方式，4层负载均衡是指在网络传输层进行流程转发，根据IP和端口进行转发，7层负载均衡完成HTTP协议负载均衡及反向代理的功能，根据url进行请求转发。
4	UI层	UI层描述了系统向pc用户、app用户、h5用户提供的产品界面。根据系统功能模块特点确定了UI层包括如下产品界面类型： 1）面向pc用户的门户系统、学习中心系统、教学管理系统、系统管理中心。 2）面向h5用户的门户系统、学习中心系统。 3）面向app用户的门户系统、学习中心系统未在上图标注，在app项目中有详细说明。
5	微服务层	微服务层将系统服务分类三类：前端服务、后端服务及系统服务。前端服务：主要为学习用户提供学习服务。后端服务：主要为管理用户提供教学管理服务。系统服务：公共服务，为系统的所有微服务提供公共服务功能。服务网关：提供服务路由、负载均衡、认证授权等服务
6	数据层	数据层描述了系统的数据存储的内容类型，持久化的业务数据使用MySQL和MongoDB保存，其中MongoDB中主要保存系统日志信息。消息队列：存储系统服务间通信的消息，本身提供消息存取服务，与微服务层的系统服务连接。索引库：存储课程信息的索引信息，本身提供索引维护及搜索的服务，与微服务层的系统服务连接。缓存：作为系统的缓存服务，存储课程信息、分类信息、用户信息等，与微服务层的所有服务连接。文件存储：提供系统静态资源文件的分布式存储服务，文件存储服务器作为CDN服务器的数据来源，CDN上的静态资源将最终在文件存储服务器上保存多份。流媒体服务：作为流媒体服务器，存储所有的流媒体文件
7	外部系统接口	1）微信、QQ、微博登录接口，本系统和微信、QQ、微博系统对接，用户输入微信、QQ、微博的账号和密码即可登录本系统。 2）微信、QQ、微博分享接口，本系统和微信、QQ、微博系统对接，可直接将本系统的课程资源信息分享到微信、QQ、微博。3）支付宝、微信、网银支付接口，本系统提供支付宝、微信、网银三种支付接口。4）短信接口，本系统与第三方平台对接短信发送接口。 5）邮件接口，本系统需要连接第三方的smpt邮件服务器对外发送电子邮件。 6）微信公众号，本系统与微信公众号平台接口，用户通过微信公众号访问H5页面。 7）点播、直播，前期视频点播与直播采用第三方服务方式，本系统与第三方点、直播服务对接，对外提供视频点播与直播服务。 8）OSS存储，前期静态资源文件的存储采用第三方服务方式，本系统与第三方提供的OSS存储服务对接，将系统的静态资源文件存储到第三方提供的OSS存储服务器上。 9）CDN，本系统与第三方CDN服务对接，使用CDN加速服务来提高本系统的访问速度
8	DevOps	DevOps（英文Development和Operations的组合）是一组过程、方法与系统的统称，用于促进开发（应用程序/软件工程）、技术运营和质量保障（QA）部门之间的沟通、协作与整合。本项目供了许多开发、运营、维护支撑的系统，包括： Eureka服务治理中心：提供服务治理服务，包括：服务注册、服务获取等。 Spring Cloud Config服务配置管理中心：提供服务配置管理服务，包括：配置文件更新、配置文件下发等。Hystrix Dashboard服务熔断监控：监控熔断的请求响应时间、成功率等。 Zipkin服务追踪监控：监控服务调用链路健康情况。 Jenkins持续集成服务：提供系统持续集成服务。 Git/GitLab代码管理服务:提供git代码管理服务。 ELK日志分析服务:提供elk日志分析服务，包括系统运行日志分析、告警服务。 Docker容器化部署服务：将本系统所有服务采用容器化部署方式。 Maven项目管理工具：提供管理项目所有的Java包依赖、项目工程打包服务

2. 技术栈

下图为项目技术架构的简图，了解项目所使用的技术栈

重点了解微服务技术栈：
学成在线服务端基于Spring Boot构建，采用Spring Cloud微服务框架。
持久层：MySQL、MongoDB、Redis、ElasticSearch
数据访问层：使用Spring Data JPA 、Mybatis、Spring Data Mongodb等
业务层：Spring IOC、Aop事务控制、Spring Task任务调度、Feign、Ribbon、Spring AMQP、Spring Data Redis等。
控制层：Spring MVC、FastJSON、RestTemplate、Spring Security Oauth2+JWT等
微服务治理：Eureka、Zuul、Hystrix、Spring Cloud Config等

3. 开发步骤

项目是基于前后端分离的架构进行开发，前后端分离架构总体上包括前端和服务端，通常是多人协作并行开发，开发步骤如下：
1、需求分析
梳理用户的需求，分析业务流程
2、接口定义
根据需求分析定义接口
3、服务端和前端并行开发
依据接口进行服务端接口开发。
前端开发用户操作界面，并请求服务端接口完成业务处理。
4、前后端集成测试
最终前端调用服务端接口完成业务。

3. CMS需求分析

1. 什么是CMS

1、CMS是什么？
CMS （Content Management System）即内容管理系统，不同的项目对CMS的定位不同，比如：一个在线教育网站，有些公司认为CMS系统是对所有的课程资源进行管理，而在早期网站刚开始盛行时很多公司的业务是网站制作，当时对CMS的定位是创建网站，即对网站的页面、图片等静态资源进行管理。
2、CMS有哪些类型？
上边也谈到每个公司对每个项目的CMS定位不同，CMS基本上分为：针对后台数据内容的管理、针对前端页面的管理、针对样式风格的管理等。比如：一个给企业做网站的公司，其CMS系统主要是网站页面管理及样式风格的管理。

3、本项目CMS的定位是什么？
本项目作为一个大型的在线教育平台，对CMS系统的定位是对各各网站（子站点）页面的管理，主要管理由于运营需要而经常变动的页面，从而实现根据运营需要快速进行页面开发、上线的需求。

2. 静态门户工程搭建

本项目CMS是对页面进行管理，对页面如何进行管理呢？我们首先搭建学成网的静态门户工程，根据门户的页面结构来分析页面的管理方案。
门户，是一个网站的入口，一般网站都有一个对外的门户，学成在线门户效果图如下：

1. 导入门户工程

1、安装WebStorm
参考“WebStorm安装手册.md”安装WebStorm-2018.2.3.exe
2、安装Nginx
下载nginx：http://nginx.org/en/download.html
本教程下载nginx-1.14.0.zip(http://nginx.org/download/nginx-1.14.0.zip)
解压nginx-1.14.0.zip到自己的计算机，双击nginx.exe即可运行。
访问：http://localhost

3、导入门户工程
将课程资料中的门户工程拷贝到代码目录。
使用WebStorm打开门户工程目录，目录的结构如下，后期会根据开发的推进进行扩充。

2. 配置虚拟主机

在nginx中配置虚拟主机：

    server {listen       80;server_name  www.xuecheng.com;ssi on;ssi_silent_errors on;location / {alias D:/webstormProjects/xc-ui-pc-static-portal/;index index.html;}}

5、配置hosts文件

修改C:\Windows\System32\drivers\etc\hosts 文件

添加127.0.0.1 www.xuecheng.com

进入浏览器，输入www.xuecheng.com

3. SSI服务端包含技术

本节分析首页的管理方案。

页面内容多如何管理？

将页面拆分成一个一个的小页面，通过cms去管理这些小页面，当要更改部分页面内容时只需要更改具体某个小页面即可。

页面拆出来怎么样通过web服务浏览呢？

使用web服务(例如nginx)的SSI技术，将多个子页面合并渲染输出。

SSI是什么？

服务端嵌入：Server Side include，是一种类似ASP的基于服务器的网页制作技术。大多数的web服务器均支持SSI命令。

ssi包含类似于jsp页面中的incluce指令，ssi是在web服务端将include指定的页面包含在网页中，渲染html网页响应给客户端。nginx、apache等多数web容器都支持SSI指令。

ssi指令如下：

<!‐‐#include virtual="/../....html"‐‐>

将首页拆分成

index.html：首页主体内容
include/header.html：头部区域
include/index_banner.html：轮播图
include/index_category.html：左侧列表导航
include/footer.html：页尾

在nginx虚拟主机中开通SSI

ssi on;
ssi_silent_errors on;

其配置参数如下：ssi on：开启ssi支持 ssi_silent_errors on：默认为off，设置为on则在处理SSI文件出错时不输出错误信息 ssi_types：默认为 ssi_types text/html，如果需要支持shtml（服务器执行脚本，类似于jsp）则需要设置为ssi_types text/shtml

测试

去掉某个#include查看页面效果

3. CMS页面管理需求

这些页面的管理流程是什么？

1）创建站点：
一个网站有很多子站点，比如：学成在线有主门户、学习中心、问答系统等子站点。具体的哪个页面是归属于具体的站点，所以要管理页面，先要管理页面所属的站点。
2）创建模板：
页面如何创建呢？比如电商网站的商品详情页面，每个页面的内容布局、板式是相同的，不同的只是内容，这个页面的布局、板式就是页面模板，模板+数据就组成一个完整的页面，最终要创建一个页面文件需要先定义此页面的模板，最终拿到页面的数据再结合模板就拼装成一个完整的页面。

3）创建页面：
创建页面是指填写页面的基本信息，如：页面的名称、页面的url地址等。
4）页面预览：
页面预览是页面发布前的一项工作，页面预览使用静态化技术根据页面模板和数据生成页面内容，并通过浏览器预览页面。页面发布前进行页面预览的目是为了保证页面发布后的正确性。
5）页面发布：
使用计算机技术将页面发送到页面所在站点的服务器，页面发布成功就可以通过浏览器来访问了。
2、本项目要实现什么样的功能？
1）页面管理
管理员在后台添加、修改、删除页面信息
2）页面预览
管理员通过页面预览功能预览页面发布后的效果。
3）页面发布
管理员通过页面发布功能将页面发布到远程门户服务器。
页面发布成功，用户即可在浏览器浏览到最新发布的页面，整个页面添加、发布的过程由于软件自动执行，无需人工登录服务器操作。

4. CMS服务端工程搭建

1. 开发工具配置

2. 导入基础工程

1. 工程结构

parent工程：父工程，提供依赖管理

common工程：通用工程，提供各层封装

model工程：模型工程，提供统一的模型类管理

utils工程：工具类工程，提供本项目所使用的工具类

Api工程：接口工程：统一管理本项目的服务接口

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-Qt7UGkvj-1634463146409)(img\dya0105.png)]

各工程的导入，以父工程为例

拷贝好代码后，点击import model，选择parent工程目录，选择maven，一直next，导入成功。

4. 导入CMS数据库

CMS采用MongoDB数据库存储CMS页面信息，原因如下：

Mongodb是非关系型数据库，存储Json格式数据 ,数据格式灵活
相比课程管理等核心数据CMS数据不重要，且没有事务管理要求。

导入过程：

创建xc_cms软件导入cms数据库
导入cms数据库

5. 页面查询接口定义

1. 定义模型

1. 需求分析

在梳理完用户需求后要去定义前后端的接口，定义后可以依据接口开发功能

本次定义页面查询接口，本接口供前端请求查询页面列表，支持分页和自定义条件查询

具体需求如下：

分页查询CmsPage集合下的数据
根据站点id，模板id和页面别名查询页面信息
接口基于HTTP get请求，响应json数据

2. 模型类介绍

接口定义离不开数据模型，根据前面对需求的分析，整个页面管理数据的模块如下

CmsSite：站点模型

CmsTemplate：页面模块

CmsPage：页面信息

2. 定义接口

1. 定义请求和响应类型

定义请求模型QueryPageRequest ，此模型作为查询条件类型

为后期扩展需求，请求类型统一继承RequestData类型

@Data
public class QueryPageRequest {// 接收页面查询的查询条件// 站点idprivate String siteId;// 页面idprivate String pageId;// 页面名称private String pageName;// 别名private String pageAliase;// 模板idprivate String templateId;// ...
}

响应结果类型，分页查询统一使用QueryResponseResult

看到注解@Data，这是什么意思？Data注解，ToString注解都是Lombok提供的注解，使用它可以消除java代码的臃肿，Lombok提供一系列的注解，使用这些注解可以不用定义getter/setter、equals、构造方法等，它会在编译时在字节码文件自动生成这些通用的方法，简化开发人员的工作。

2. 定义接口

在Api接口工程专门定义接口，在Api工程单独定义接口的原因：

接口集中管理
Api工程的接口将作为各微服务远程调用使用

页面查询接口定义如下

public interface CmsPageControllerApi {// 页面查询public QueryResponseResult findList(int page, int size, QueryPageRequest queryPageRequest);
}

此接口编写后会在CMS服务工程编写Controller类实现此接口

6. 页面查询服务端开发

1. 创建CMS服务工程

1. 创建CMS工程结构

创建maven工程，CMS工程的名称为xc-service-manage-cms ,父工程为parent

pom文件所需依赖如下

<dependencies><dependency><groupId>com.xuecheng</groupId><artifactId>xc-service-api</artifactId><version>1.0-SNAPSHOT</version></dependency><dependency><groupId>com.xuecheng</groupId><artifactId>xc-framework-model</artifactId><version>1.0-SNAPSHOT</version></dependency><dependency><groupId>com.xuecheng</groupId><artifactId>xc-framework-utils</artifactId><version>1.0-SNAPSHOT</version></dependency><dependency><groupId>com.xuecheng</groupId><artifactId>xc-framework-common</artifactId><version>1.0-SNAPSHOT</version></dependency><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-freemarker</artifactId></dependency><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-data-mongodb</artifactId></dependency><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-amqp</artifactId></dependency><dependency><groupId>com.squareup.okhttp3</groupId><artifactId>okhttp</artifactId></dependency><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-test</artifactId></dependency>
</dependencies>

创建基本的包结构

com.xuecheng.manage_cms.config：配置类目录，数据库配置、MQ配置等
com.xuecheng.manage_cms.dao：dao接口目录
com.xuecheng.manage_cms.service：service类目录
com.xuecheng.manage_cms.web.controller：controller类目录

配置文件

在classpath下配置application.yml

server:port: 31001
spring:application:name: xc-service-manage-cmsdata:mongodb:uri: mongodb://root:123@localhost:27017database: xc_cms

拷贝logback-spring.xml，作为日志配置文件

springboot启动类

注意扫描的包除了自身的还有其他的

@SpringBootApplication
@EntityScan("com.xuecheng.framework.domain.cms")//扫描实体类
@ComponentScan(basePackages = {"com.xuecheng.api"})//扫描接口
@ComponentScan(basePackages = {"com.xuecheng.manage_cms"})//扫描自己的,方便查阅
public class ManageCmsApplication {public static void main(String[] args) {SpringApplication.run(ManageCmsApplication.class,args);}
}

2. 测试Controller

使用springMVC完成接口实现开发，暂时使用静态的测试数据

@RestController
@RequestMapping("/cms/page")
public class CmsPageController implements CmsPageControllerApi {@GetMapping("/list/{page}/{size}")@Overridepublic QueryResponseResult findList(@PathVariable("page") int page,@PathVariable("size") int size, QueryPageRequest queryPageRequest) {// 暂时用静态数据QueryResult<CmsPage> queryResult = new QueryResult<>();List<CmsPage> list = new ArrayList<>();CmsPage cmsPage = new CmsPage();cmsPage.setPageName("测试页面");list.add(cmsPage);queryResult.setList(list);queryResult.setTotal(1);QueryResponseResult queryResponseResult = new QueryResponseResult(CommonCode.SUCCESS,queryResult);return queryResponseResult;}
}

使用浏览器测试

输入：<http://localhost:31001/cms/page/list/1/2>，查询第一页，每页显示2条记录

2. Dao

1. 分页查询测试

1. 定义dao接口

使用Spring Data MongoDB完成MongoDB数据库的查询，

public interface CmsPageRepository extends MongoRepository<CmsPage,String> {}

2. 编写测试类

@SpringBootTest
@RunWith(SpringRunner.class)
public class CmsPageRepositoryTest {@Autowiredprivate CmsPageRepository cmsPageRepository;@Testpublic void testFindAll(){List<CmsPage> all = cmsPageRepository.findAll();System.out.println(all);}@Testpublic void testFindPage(){// 分页参数int page = 0;//从0开始int size = 10;Pageable pageable = PageRequest.of(page,size);Page<CmsPage> all = cmsPageRepository.findAll(pageable);System.out.println(all);}
}

2. 基础方法测试

dao继承了MongoRepository，在MongoRepository中定义了很多现成的方法，基础的增删改查

// 添加
@Test
public void testAdd(){// 定义实体类CmsPage cmsPage = new CmsPage();cmsPage.setSiteId("s01");cmsPage.setTemplateId("t01");cmsPage.setPageName("测试页面");cmsPage.setPageCreateTime(new Date());List<CmsPageParam> cmsPageParams = new ArrayList<>();CmsPageParam cmsPageParam = new CmsPageParam();cmsPageParam.setPageParamName("param1");cmsPageParam.setPageParamValue("value1");cmsPageParams.add(cmsPageParam);cmsPage.setPageParams(cmsPageParams);cmsPageRepository.save(cmsPage);System.out.println(cmsPage);
}// 删除
@Test
public void testDelete(){cmsPageRepository.deleteById("5cf37f565ed156391ca77e78");
}// 修改
@Test
public void testUpdate(){// 查询对象Optional<CmsPage> optional = cmsPageRepository.findById("5cf381fb5ed1561fe42f9d69");if(optional.isPresent()){CmsPage cmsPage = optional.get();// 设置要修改的值cmsPage.setPageAliase("test002");//...// 修改CmsPage save = cmsPageRepository.save(cmsPage);System.out.println(save);}
}

关于Optional:

Optional是JDK8引入的类型，是个容器对象，包括我们所需的对象，通过isPresent方法判断对象是否为空，返回false，表示为空

优点是：1. 提醒非空判断；2. 将对象非空检测标准化

3. 自定义dao方法

和JPA一样，也有很多自定义方法，按照findByXxx,findByXxxAndYyy,countByXxxANDYyy等规则定义方法。

public interface CmsPageRepository extends MongoRepository<CmsPage,String> {//根据页面名称查询CmsPage findByPageName(String pageName);//根据页面名称和类型查询CmsPage findByPageNameAndPageType(String pageName,String pageType);//根据站点和页面类型查询记录数int countBySiteIdAndPageType(String siteId,String pageType);//根据站点和页面类型分页查询Page<CmsPage> findBySiteIdAndPageType(String siteId,String pageType, Pageable pageable);
}

3. service

定义页面查询方法，根据条件查询暂时不实现

@Service
public class PageService {@Autowiredprivate CmsPageRepository cmsPageRepository;/***  页面查询方法* @param page 页码，从1开始计数* @param size 每页记录数* @param queryPageRequest 查询条件* @return*/public QueryResponseResult findList(int page, int size, QueryPageRequest queryPageRequest) {// 分页参数if(page<=0){page=1;}if(size<=0){size=10;}page = page-1;Pageable pageable = PageRequest.of(page,size);Page<CmsPage> all = cmsPageRepository.findAll(pageable);QueryResult queryResult = new QueryResult();queryResult.setTotal(all.getTotalElements());//数据总记录数queryResult.setList(all.getContent());//数据列表QueryResponseResult queryResponseResult = new QueryResponseResult(CommonCode.SUCCESS,queryResult);return queryResponseResult;}
}

4. Controller

使用springMVC完成接口实现开发，将静态替换为service层的调用

测试：同静态的测试

7. 页面查询接口测试

当接口定义完成，可以使用工具生成接口文档，前端人员查看接口文档即可进行前端开发

两种接口开发工具，Swagger和Postman。

1. Swagger

1. 介绍

OpenAPI规范（OpenAPI Specification 简称OAS）是Linux基金会的一个项目，试图通过定义一种用来描述API格式或API定义的语言，来规范RESTful服务开发过程

Swagger是全球最大的OpenAPI规范（OAS）API开发工具框架，支持从设计和文档到测试和部署的整个API生命周期的开发

Spring Boot 可以集成Swagger，生成Swagger接口，Spring Boot是Java领域的神器，它是Spring项目下快速构建项目的框架。

2. Swagger常用注解

在Java类中添加Swagger的注解即可生成Swagger接口，常用Swagger注解如下：

@Api：修饰整个类，描述Controller的作用 @ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述 @ApiModel：用对象来接收参数 @ApiModelProperty：用对象接收参数时，描述对象的一个字段 @ApiResponse：HTTP响应其中1个描述 @ApiResponses：HTTP响应整体描述 @ApiIgnore：使用该注解忽略这个API @ApiError ：发生错误返回的信息 @ApiImplicitParam：一个请求参数
@ApiImplicitParams：多个请求参数

3. Swagger接口定义

修改接口工程中页面查询接口，添加Swagger注解

@Api(value="cms页面管理接口",description = "cms页面管理接口，提供页面的增、删、改、查")
public interface CmsPageControllerApi {// 页面查询@ApiOperation("分页查询页面列表")@ApiImplicitParams({@ApiImplicitParam(name="page",value = "页码",required=true,paramType="path",dataType="int"),@ApiImplicitParam(name="size",value = "每页记录数",required=true,paramType="path",dataType="int")})public QueryResponseResult findList(int page, int size, QueryPageRequest queryPageRequest);
}

在QueryPageRequest类中使用注解 ApiModelProperty 对属性注释：

@Data
public class QueryPageRequest {// 接收页面查询的查询条件// 站点id@ApiModelProperty("站点id")private String siteId;// 页面id@ApiModelProperty("页面ID")private String pageId;// 页面名称@ApiModelProperty("页面名称")private String pageName;// 别名@ApiModelProperty("页面别名")private String pageAliase;// 模板id@ApiModelProperty("模版id")private String templateId;// ...
}

4. 测试

Swagger接口生成工作原理：

1、系统启动，扫描到api工程中的Swagger2Configuration类
2、在此类中指定了包路径com.xuecheng，找到在此包下及子包下标记有@RestController注解的controller类
3、根据controller类中的Swagger注解生成接口文档。

启动cms服务工程，查看接口文档，请求：<http://localhost:31001/swagger-ui.html>

2. Postman

略