Swagger安装及使用

前言

在前后端分离开发的过程中，前端和后端需要进行api对接进行交互，就需要一个api规范文档，方便前后端的交互，但api文档不能根据代码的变化发生实时动态的改变，这样后端修改了接口，前端不能及时获取最新的接口，导致调用出错，需要手动维护api文档，加大了开发的工作量和困难，而swagger的出现就是为了解决这一系列的问题。

Swagger介绍

Swagger是一套基于OpenAPI规范构建的开源工具，使用RestApi

1. 代码变，文档变
2. 跨语言，支持多种语言
3. Swagger-ui 呈现出来的是一份可交互式的API文档，可以直接在文档页面尝试API的调用
4. 可以将文档规范导入相关工具（postman、soapui），这些工具将会为我们自动地创建自动化测试

RestApi格式是根据请求的方式决定本次请求的一个操作，譬如：get-->读，post-->写（增、删、改），put-->修改，delete-->删除
OpenApi与语言无关，只是一种规范，可以使用yaml和json格式进行编写，这样更利于我们和机器进行阅读

Swagger主要包含了以下三个部分：

• Swagger editor：基于浏览器的编辑器，我们可以使用它编写我们OpenApi规范(yaml或者json配置）
• Swagger UI：他会将我们编写的OpenApi规范呈现为交互式的API文档，后文我将使用浏览器来查看并且操作我们的RestApi
• Swagger Codegen：它可以通过OpenApi规范定义的任何API生成服务器存根和客户端SDK来简化构建过程

springfox

使用swagger时如果碰见版本更新迭代时，只需要更改swagger的描述文件即可，但是在频繁的更新项目版本时很多开发人员认为即使修改描述文件（yml或json文件）也是一定的工作负担，久而久之就直接修改代码，而不去修改描述文件了，这样基于描述文件生成接口文档也失去了意义。
Marty Pitt编写了一个基于spring的组件swagger-springmvc,Spring-fox就是根据这个组件发展而来的全新项目;
Spring-fox是根据代码生成接口文档，所以正常的进行更新项目版本，修改代码即可，而不需要跟随修改描述文件(yml或json文件）;
spring-fox利用自身AOP特性，把swagger集成进来，底层还是Swagger，但是使用起来却方便很多，所以在实际开发中，都是直接使用spring-fox。

Swagger安装

环境准备

Java环境搭建
IDEA工具

IDEA新建Spring Boot项目

两种新建项目的方式

第一种方式

解压文件后，用idea打开

等待自动下载及配置，完成后会自动创建项目结构

第二种方式

File→New→Project




等待自动下载及配置

Maven与Spring Initializr的区别

• Maven‌：
  ‌定义‌：Maven是一个项目管理和构建工具，用于管理Java项目的构建、依赖关系和报告。它使用POM（Project Object Model）文件来描述项目。
  ‌功能‌：适用于各种类型的Java项目，管理项目的依赖关系、构建生命周期等。
  ‌使用场景‌：如果你计划构建一个基于Spring Boot的项目，并且需要更灵活的项目管理和构建功能，使用Maven可能更为合适。
• Spring Initializr‌：
  ‌定义‌：Spring Initializr是一个在线工具，用于快速启动Spring Boot项目。它提供了一些基本的项目配置选项，如项目类型、语言、Spring Boot版本和依赖等。
  ‌功能‌：专门用于快速创建基于Spring Boot的项目，提供了一些默认的配置和依赖项。
  ‌使用场景‌：如果你需要快速生成一个标准的Spring Boot项目基础结构，Spring Initializr是一个更便捷的选择。

Spring Boot=Spring + Spring MVC（模型-视图-控制器（MVC）---前端接收、路由等控制）

依赖配置

修改JDK版本

修改spring-boot-starter-parent依赖版本

版本修改为2.5.7

添加Swagger依赖

查找依赖库工具
https://mvnrepository.com/

点击刷新，自动安装及更新依赖

运行Spring Boot项目

启动类中添加注解@EnableSwagger2

启动项目

启动成功

8080正常访问Swagger
访问地址：http://localhost:8080/swagger-ui.html

运行报java环境错误时，配置查看及修改java版本
POM.xml→java.version---修改自己对应java版本
File→Project Structure

• →Projcet
  • projcet SDK---修改自己对应java版本
  • Project language level---修改自己对应java版本
• →Modules
  • →Sources→language level---修改自己对应java版本
  • →Dependencies→Module SDK---修改自己对应java版本

File→Settings→Build, Execution,Deployment → Compiler → Java Compiler

• Project bytecode version---修改自己对应java版本
• Per-module bytecode version---修改自己对应java版本

IDEA中报“无效的目标发行版：14”问题的解决方法

Swagger基础使用

配置Swagger

新建config包，并创建SwaggerConfig类

编写方法并使用Swagger

注意类需要注解@RestController，否则Swagger无法识别到
@enableSwagger2：是springfox提供的一个注解，代表swagger2相关技术开启,会扫描当前类所在包，以及子包中所有的类型中的注解，做swagger文档的定值

启动项目，访问Swagger

Swagger更多使用方法

Spring MVC与Swagger常用注解