非 Spring Boot 项目中集成 Swagger：一步一步指南

java

2024-03-19 15:42:07

非 Spring Boot 项目中集成 Swagger：一步一步指南

简介

Swagger 是一个强大的工具，可帮助开发人员生成交互式的 RESTful API 文档。本文将指导你如何将 Swagger 集成到基于 Spring Framework 的非 Spring Boot 项目中。

先决条件

Spring Framework 4.3 或更高版本
Swagger 2.5.0 或更高版本

步骤

1. 添加 Swagger 依赖项

在项目的 pom.xml 文件中添加以下依赖项：

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.5.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.5.0</version>
</dependency>

2. 配置资源处理程序

在 WebConfig 类中配置资源处理程序以公开 Swagger UI 和 WebJAR 资源：

@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
    registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
    registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
}

3. 配置 Swagger

创建 SwaggerConfig 类来配置 Swagger：

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
            .select()
            .apis(RequestHandlerSelectors.any())
            .paths(PathSelectors.any())
            .build();
    }
}

4. 配置 web.xml

在 web.xml 中添加以下配置：

<servlet-mapping>
    <servlet-name>swagger-api</servlet-name>
    <url-pattern>/swagger-api/*</url-pattern>
</servlet-mapping>

<servlet>
    <servlet-name>swagger-api</servlet-name>
    <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
    <init-param>
        <param-name>contextConfigLocation</param-name>
        <param-value>/WEB-INF/swagger-servlet-context.xml</param-value>
    </init-param>
    <load-on-startup>2</load-on-startup>
</servlet>

5. 配置 swagger-servlet-context.xml

创建 swagger-servlet-context.xml 文件：

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:context="http://www.springframework.org/schema/context"
       xmlns:mvc="http://www.springframework.org/schema/mvc"
       xsi:schemaLocation="http://www.springframework.org/schema/beans
       http://www.springframework.org/schema/beans/spring-beans-4.3.xsd
       http://www.springframework.org/schema/context
       http://www.springframework.org/schema/context/spring-context-4.3.xsd
       http://www.springframework.org/schema/mvc
       http://www.springframework.org/schema/mvc/spring-mvc-4.3.xsd">

    <context:component-scan base-package="com.example.controller" />

    <mvc:annotation-driven />
</beans>