杂七杂八之Swagger环境搭建(Java版本)

杂七杂八之Swagger环境搭建(Java版本)

在现代Web开发中,API文档的生成和维护是一个非常重要的环节。Swagger是一个强大的工具,它能够帮助开发者自动生成RESTful API的文档,并提供了一个用户友好的界面来测试这些API。本文将详细介绍如何在Java项目中搭建Swagger环境,包括所需的依赖、配置步骤以及如何使用Swagger UI来查看和测试API。

环境准备

在开始之前,确保你的开发环境中已经安装了以下软件:

● Java Development Kit (JDK) 1.8 或更高版本

● Maven 3.6.1(自己的应用环境)

● 一个支持Java的IDE,如 IntelliJ IDEA 或 Eclipse,本人使用IDEA

添加Swagger依赖

Maven项目

如果你的项目是基于Maven的,可以在pom.xml文件中添加以下依赖:

xml 复制代码
<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>

Gradle项目

如果你的项目是基于Gradle的,可以在build.gradle文件中添加以下依赖:

groovy 复制代码
dependencies {
    implementation 'io.springfox:springfox-swagger2:2.9.2'
    implementation 'io.springfox:springfox-swagger-ui:2.9.2'
}

配置Swagger

创建Swagger配置类

在你的Spring Boot项目中,创建一个新的配置类来启用Swagger。例如,可以创建一个名为SwaggerConfig.java的类:

java 复制代码
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
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;

/**
 * @author Sam Zhang
 * @date 2024-11-06 09:45:45
 * @since 0.0.1
 * 注释:swagger接口注释
 */

@EnableSwagger2
@Configuration
//是否开启swagger,正式环境一般是需要关闭的(避免不必要的漏洞暴露!),可根据springboot的多环境配置进行设置
public class Swagger2Config implements WebMvcConfigurer {
    // swagger2的配置文件,这里可以配置swagger2的一些基本的内容,比如扫描的包等等
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                // 为当前包路径
                .apis(RequestHandlerSelectors.basePackage("com.demo.llmanalysis"))
                .paths(PathSelectors.any())
                .build();
    }
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/**")
                .addResourceLocations("classpath:/static/");
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
    // 构建 api文档的详细信息函数,注意这里的注解引用的是哪个
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                // 页面标题
                .title("JMeter日志错误日志大模型分析服务")
                // 创建人信息
                .contact(new Contact("Sam Zhang",  "https://blog.csdn.net/u012151594?type=blog",  "[email protected]"))
                // 版本号
                .version("1.0")
                // 描述
                .description("LLMAnalysis API 描述")
                .build();
    }
}

在这个配置中,RequestHandlerSelectors.basePackage指定了需要扫描的控制器包,PathSelectors.any()表示所有路径都会被包含在文档中。

启用Swagger UI

Swagger UI是一个用于查看和测试API的前端界面。在上述配置中,通过添加springfox-swagger-ui依赖,Swagger UI已经被自动集成到项目中。启动应用后,可以通过访问http://localhost:8080/swagger-ui.html来

测试Swagger

启动你的Spring Boot应用,然后在浏览器中访问http://localhost:8080/swagger-ui.html。你应该能够看到Swagger UI界面,其中列出了所有可用的API端点。你可以点击每个端点来查看详细的请求和响应信息,并直接在界面上测试API。

总结

通过上述步骤,你已经成功地在Java项目中集成了Swagger。Swagger不仅能够帮助你自动生成API文档,还能提供一个强大的测试工具,极大地提高了开发效率和API的可维护性。希望本文对你有所帮助,祝你在API开发的道路上越走越远!

相关推荐
木昜先生10 分钟前
知识点:深入理解 JVM 内存管理与垃圾回收
java·jvm·后端
115432031q13 分钟前
基于SpringBoot+Vue实现的旅游景点预约平台功能十三
java·前端·后端
战族狼魂17 分钟前
基于SpringBoot+PostgreSQL+ROS Java库机器人数据可视化管理系统
java·spring boot·postgresql
半个脑袋儿24 分钟前
Java线程控制: sleep、yield、join深度解析
java
猫猫头有亿点炸27 分钟前
C语言大写转小写2.0
c语言·开发语言
小智疯狂敲代码28 分钟前
Spring MVC-DispatcherServlet 的源码解析
java·面试
int0x0328 分钟前
Java中的内存"瘦身术":揭秘String Deduplication
java
半个脑袋儿29 分钟前
Java日期格式化中的“YYYY”陷阱:为什么跨年周会让你的年份突然+1?
java·后端
A达峰绮37 分钟前
设计一个新能源汽车控制系统开发框架,并提供一个符合ISO 26262标准的模块化设计方案。
大数据·开发语言·经验分享·新能源汽车
CHQIUU42 分钟前
Java 设计模式心法之第25篇 - 中介者 (Mediator) - 用“中央协调”降低对象间耦合度
java·设计模式·中介者模式