目录
■1．前言・Swagger介绍
■2．例子，如果基于Spring Boot项目，实现Swagger---非常简单
2．1．已有的SpringBoot项目
2．2．修改POM文件
2．3．添加Config文件
2．4．访问
2．5．访问效果以及对应的代码
效果
代码
2．６．类的标注
2．7．启动Log
2．8．xxx
2．9．xxx
■３．非Spring 项目中，Swagger的运用
3．0．Sping介绍
3．1．简介
3．2．SwaggerConfig
3．3．配置Swagger相关Bean
3．4．访问
3．5．对于非Spring工程，如何加载Swagger的配置类
3．6．Web工程，如何配置，能让一个类在服务启动的时候，被加载
方法1（最基本方法）：
方法2：@WebListener
3．7．ServletContextListener
＝＝＝＝
■1．前言・Swagger介绍
项目去IF设计书化，使用Swagger生成API接口。
先了解一下Swagger
Swagger是一组开源工具，用于设计、构建、文档化和测试RESTful API。它提供了一种基于JSON或YAML格式的API描述语言，可以定义API的操作、参数、响应和安全规范，并生成易于阅读和交互的API文档。Swagger还提供了一组可视化工具，包括Swagger UI和Swagger Editor，可以帮助开发人员快速构建和测试API。使用Swagger可以提高API的可读性、可维护性和交互性，从而促进API的开发和使用。
学习资料
官方文档：Swagger Documentation
Swagger Editor：Swagger Editor
Swagger UI：REST API Documentation Tool | Swagger UI
使用Swagger自动生成API文档：https://www.cnblogs.com/kevingrace/p/7883099.html
使用Swagger构建RESTful API：https://www.jianshu.com/p/9b1b75b4f3ea
Swagger入门教程：https://www.cnblogs.com/panpanwelcome/p/10094733.html
Swagger的使用及其原理简介：https://www.jianshu.com/p/a5f6e5e9f4cf
Spring Boot集成Swagger：https://www.jianshu.com/p/03c7b314d1f8
===
■2．例子，如果基于Spring Boot项目，实现Swagger---非常简单
2．1．已有的SpringBoot项目
SpringBoot + Thymeleaf 之 HelloWorld_sun0322的博客-CSDN博客
＝＝＝＝
2．2．修改POM文件
<!--swagger依赖-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<!--swagger ui-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>＝＝＝
2．3．添加Config文件
package com.sxz.test.one.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import com.google.common.base.Predicates;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2
public class Swagger2Config {
/**
* 创建API应用
* apiInfo() 增加API相关信息
* 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，
* 指定扫描的包路径来定义指定要建立API的目录。
* @return
*/
@Bean
public Docket coreApiConfig(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(adminApiInfo())
.groupName("xxxApi")
.select()
//只显示user下面的路径
.paths(Predicates.and(PathSelectors.regex("/user/.*")))
.apis(RequestHandlerSelectors.basePackage("com.sxz"))
.build();
}
private ApiInfo adminApiInfo(){
return new ApiInfoBuilder()
.title("XXXX--api文档")
.description("My Spring boot Api 介绍。。。。。")
.version("1.0")
.contact(new Contact("zhangsan","https://blog.csdn.net/sxzlc","123456789@sun.com"))
.build();
}
}
＝＝＝
2．4．访问
https://10.10.10.194/swagger-ui.html#/
＝＝＝
2．5．访问效果以及对应的代码
效果
代码
package com.sxz.test.one.controller;
import java.util.List;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.RequestMapping;
import com.sxz.test.one.entity.User;
import com.sxz.test.one.service.UserService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import lombok.extern.slf4j.Slf4j;
@Api(value = "User Info")
@Controller
@RequestMapping("/user")
@Slf4j
public class UserController2 {
@Autowired
UserService userService;
@ApiOperation(value = "All User Info",notes = "Find All User Info")
@RequestMapping("/findAll2")
public String findAll(
@ApiParam(value = "Model",required = true,example = "example model")
Model model){
log.info("Hello World !-------!");
List<User> userList = userService.findAll();
model.addAttribute("userList",userList);
return "helloThymeleafMyBatis.html";
}
}
xxx
2．６．类的标注
xxxx
在完成了上述配置后，其实已经可以生产文档内容，但是这样的文档主要针对请求本身，描述的主要来源是函数的命名，通常需要自己增加一些说明来丰富文档内容。
Swagger使用的注解及其说明：
@Api：用在类上，说明该类的作用。
@ApiOperation：注解来给API增加方法说明。
@ApiParam：定义在参数上
@ApiResponses：用于表示一组响应
@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
l code：数字，例如400
l message：信息，例如"请求参数没填好"
l response：抛出异常的类@ApiModel：描述一个Model的信息（一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候）
l @ApiModelProperty：描述一个model的属性
@ApiImplicitParams: 用在方法上包含一组参数说明。
@ApiImplicitParam：用来注解来给方法入参增加说明。
@ApiImplicitParam的参数说明：
paramType：指定参数放在哪个地方
header：请求参数放置于Request Header，使用@RequestHeader获取 query：请求参数放置于请求地址，使用@RequestParam获取 path：（用于restful接口）–>请求参数的获取：@PathVariable body：（不常用） form（不常用）
name：参数名
dataType：参数类型
required：参数是否必须传
true | false
value：说明参数的意思
defaultValue：参数的默认值
xxxx
2．7．启动Log
。。。。。。。
[2023-07-31 19:04:20.990] [level: INFO] [Thread: main] [ Class:org.springframework.boot.web.servlet.context.ServletWebServerApplicationContext >> Method: prepareWebApplicationContext:285 ]
INFO:Root WebApplicationContext: initialization completed in 5824 ms
[2023-07-31 19:04:24.578] [level: INFO] [Thread: main] [ Class:springfox.documentation.spring.web.PropertySourcedRequestMappingHandlerMapping >> Method: initHandlerMethods:69 ]
INFO:Mapped URL path [/v2/api-docs] onto method [springfox.documentation.swagger2.web.Swagger2Controller#getDocumentation(String, HttpServletRequest)]
[2023-07-31 19:04:24.889] [level: INFO] [Thread: main] [ Class:org.springframework.scheduling.concurrent.ThreadPoolTaskExecutor >> Method: initialize:181 ]
INFO:Initializing ExecutorService 'applicationTaskExecutor'
[2023-07-31 19:04:25.143] [level: INFO] [Thread: main] [ Class:org.springframework.boot.autoconfigure.web.servlet.WelcomePageHandlerMapping >> Method: <init>:53 ]
INFO:Adding welcome page: class path resource [static/index.html]
。。。。。。。
2．8．xxx
xxxx
2．9．xxx
xxxx
＝＝＝
■３．非Spring 项目中，Swagger的运用
3．0．Sping介绍
Spring Boot，Sprint Batch，ThymeLeaf 学习_sun0322的博客-CSDN博客
xxxx
3．1．简介
Swagger是一种用于创建、文档化和测试Restful API的工具，不限于特定的框架或工程。即使你的web工程不是基于Spring或Spring Boot的，你仍然可以使用Swagger来实现API文档化和测试。
如果你的web工程不是基于Spring或Spring Boot的，你可以使用Swagger2配置Swagger，提供API文档化和测试的功能。下面给出一个示例配置：
xxxx
3．2．SwaggerConfig
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2
public class SwaggerConfig {
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.basePackage("com.example.api")) // 修改为你的API接口所在的包路径
.paths(PathSelectors.any())
.build()
.apiInfo(apiInfo());
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("API文档")
.description("描述你的API")
.version("1.0")
.build();
}
}xxxx
3．3．配置Swagger相关Bean
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@Configuration
public class AppConfig {
@Bean
public SwaggerConfig swaggerConfig() {
return new SwaggerConfig();
}
}===
3．4．访问
启动工程并访问Swagger UI：当你的工程启动后，你可以通过访问Swagger UI来查看生成的API文档。Swagger UI的访问地址一般是
http://localhost:port/swagger-ui.html，其中port是你的web应用的端口号。==
需要注意的是，以上示例代码是以Java配置的方式示范，如果你的工程使用其他配置方式（如XML配置），你需要相应地进行调整。
==
以上是一个基本的Swagger2配置示例，通过在工程中配置Swagger，你可以实现API文档化和测试的功能。具体的配置细节可能会因为工程的不同而有所差异，你可以根据Swagger官方文档或相关的API文档进行调整和修改。
xxxx
3．5．对于非Spring工程，如何加载Swagger的配置类
对于非Spring工程，如果你想要让程序加载Swagger的配置类
public class MainClass {
public static void main(String[] args) throws Exception {
Class<?> swaggerConfigClass = Class.forName("你的包名.SwaggerConfig"); // 修改为SwaggerConfig类所在的包名
}
}xxx
调用SwaggerConfig类的api()方法：通过反射调用SwaggerConfig类中的api()方法来获取Docket对象。
public class MainClass {
public static void main(String[] args) throws Exception {
Class<?> swaggerConfigClass = Class.forName("你的包名.SwaggerConfig"); // 修改为SwaggerConfig类所在的包名
Object swaggerConfigObject = swaggerConfigClass.newInstance();
Method apiMethod = swaggerConfigClass.getDeclaredMethod("api");
Docket docket = (Docket) apiMethod.invoke(swaggerConfigObject);
}
}使用Docket对象进行Swagger的配置和初始化。
public class MainClass {
public static void main(String[] args) throws Exception {
Class<?> swaggerConfigClass = Class.forName("你的包名.SwaggerConfig"); // 修改为SwaggerConfig类所在的包名
Object swaggerConfigObject = swaggerConfigClass.newInstance();
Method apiMethod = swaggerConfigClass.getDeclaredMethod("api");
Docket docket = (Docket) apiMethod.invoke(swaggerConfigObject);
// 根据你的实际需求，进行其他的Swagger配置（例如设置路径，设置API文档信息等）
// 初始化Swagger
Swagger swagger = docket.initialize();
// 可以根据需要将Swagger对象保存下来，供其他需要使用Swagger的地方使用
}
}sss
以上是在非Spring工程中手动加载Swagger配置类的方法，你可以根据实际情况进行调整。需要注意的是，这种方式需要手动处理加载和初始化，相对于Spring工程中的自动注入来说，比较繁琐。如果你的项目是非常简单的项目，也可以考虑使用Spring或Spring Boot来简化Swagger的配置和集成。
3．6．Web工程，如何配置，能让一个类在服务启动的时候，被加载
方法1（最基本方法）：
首先，创建一个类实现
javax.servlet.ServletContextListener接口并重写contextInitialized方法，该方法会在Web应用启动时被调用。在该方法中，你可以执行你想要在服务启动时加载的逻辑。
↓
import javax.servlet.ServletContextEvent;
import javax.servlet.ServletContextListener;
public class MyServletContextListener implements ServletContextListener {
@Override
public void contextInitialized(ServletContextEvent servletContextEvent) {
// 这里写你想要在服务启动时加载的逻辑
}
@Override
public void contextDestroyed(ServletContextEvent servletContextEvent) {
// 服务关闭时的逻辑
}
}然后，在
web.xml中配置该监听器。找到web.xml文件，添加以下代码：
<listener>
<listener-class>你的包名.MyServletContextListener</listener-class> <!-- 修改为你的类的全限定名 -->
</listener>xxx
当你的Web应用启动时，
MyServletContextListener类的contextInitialized方法将会被调用，在该方法中可以执行你想要在服务启动时加载的逻辑。＝＝＝
方法2：@WebListener
注意：在最新的Servlet规范和Servlet 3.0之后，你还可以使用注解的方式配置
ServletContextListener。你可以在想要加载的类上添加@WebListener注解，并将其放置在类上方。
xxx
import javax.servlet.annotation.WebListener;
import javax.servlet.ServletContextEvent;
import javax.servlet.ServletContextListener;
@WebListener
public class MyServletContextListener implements ServletContextListener {
@Override
public void contextInitialized(ServletContextEvent servletContextEvent) {
// 这里写你想要在服务启动时加载的逻辑
}
@Override
public void contextDestroyed(ServletContextEvent servletContextEvent) {
// 服务关闭时的逻辑
}
}↑
这种方式更简洁，并且不需要在
web.xml中进行配置。无论是使用
web.xml配置还是使用注解配置ServletContextListener，都可以达到在Web服务启动时加载某个类的目的。
xxx
3．7．ServletContextListener
===
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
package javax.servlet;
import java.util.EventListener;
/**
* Interface for receiving notification events about ServletContext
* lifecycle changes.
*
* <p>In order to receive these notification events, the implementation
* class must be either declared in the deployment descriptor of the web
* application, annotated with {@link javax.servlet.annotation.WebListener},
* or registered via one of the addListener methods defined on
* {@link ServletContext}.
*
* <p>Implementations of this interface are invoked at their
* {@link #contextInitialized} method in the order in which they have been
* declared, and at their {@link #contextDestroyed} method in reverse
* order.
*
* @see ServletContextEvent
*
* @since Servlet 2.3
*/
public interface ServletContextListener extends EventListener {
/**
* Receives notification that the web application initialization
* process is starting.
*
* <p>All ServletContextListeners are notified of context
* initialization before any filters or servlets in the web
* application are initialized.
*
* @param sce the ServletContextEvent containing the ServletContext
* that is being initialized
*/
public void contextInitialized(ServletContextEvent sce);
/**
* Receives notification that the ServletContext is about to be
* shut down.
*
* <p>All servlets and filters will have been destroyed before any
* ServletContextListeners are notified of context
* destruction.
*
* @param sce the ServletContextEvent containing the ServletContext
* that is being destroyed
*/
public void contextDestroyed(ServletContextEvent sce);
}
xxx
===
![[SSM]Spring6整合JUnit5与集成MyBatis3.5](https://img-blog.csdnimg.cn/f31859d78ada4fba96717720bdd693f1.png)
