Swagger之Hello World ！

目录

■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*/@Beanpublic 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","[e-mail]")).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 {@AutowiredUserService 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 {@Beanpublic 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文档信息等）// 初始化SwaggerSwagger 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 {@Overridepublic void contextInitialized(ServletContextEvent servletContextEvent) {// 这里写你想要在服务启动时加载的逻辑}@Overridepublic 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 {@Overridepublic void contextInitialized(ServletContextEvent servletContextEvent) {// 这里写你想要在服务启动时加载的逻辑}@Overridepublic 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

===