Spring Boot集成Swagger API文档自动生成

Spring Boot集成Swagger API文档自动生成

大家好，我是微赚淘客返利系统3.0的小编，是个冬天不穿秋裤，天冷也要风度的程序猿！

Swagger是一个广泛使用的API文档生成工具，它允许开发者定义API接口的结构，然后自动生成文档。Spring Boot与Swagger的集成可以极大地简化API文档的生成和管理过程。

添加Swagger依赖

首先，需要在Spring Boot项目的pom.xml文件中添加Swagger的依赖。

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

配置Swagger

接下来，需要配置Swagger的Docket bean，这通常在配置类中完成。

import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.builders.PathSelectors;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import cn.juwatech.config.SwaggerConfig;

@Configuration
public class SwaggerConfig {

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

使用Swagger注解

Swagger提供了一系列的注解，可以用来丰富API文档的信息。

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class SampleController {

    @GetMapping("/sample")
    @Operation(summary = "Sample API", description = "This is a sample API")
    @ApiResponse(responseCode = "200", description = "OK")
    public String sampleApi() {
        return "Sample response";
    }
}

配置Swagger UI

Swagger UI是一个Web界面，可以直观地展示API文档。可以通过配置Swagger的SwaggerUiConfiguration来自定义UI。

import springfox.documentation.swagger.web.SwaggerUiConfiguration;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SwaggerUiConfig {

    @Bean
    public SwaggerUiConfiguration swaggerUiConfiguration() {
        return new SwaggerUiConfiguration(
            null, 
            null, 
            null, 
            null, 
            null, 
            "/api-docs", 
            true, 
            true, 
            null, 
            null, 
            null, 
            null
        );
    }
}

访问Swagger UI

配置完成后，可以通过访问http://localhost:8080/swagger-ui/来查看API文档。

配置全局异常处理

在Swagger文档中，API的异常信息也很重要。可以通过配置全局异常处理器来展示异常信息。

import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.ResponseStatus;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import org.springframework.http.HttpStatus;

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(Exception.class)
    @ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)
    public String handleException(Exception e) {
        return e.getMessage();
    }
}

集成Spring Security

如果API需要认证，可以集成Spring Security来保护Swagger UI。

import org.springframework.context.annotation.Bean;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.web.SecurityFilterChain;

@Configuration
@EnableWebSecurity
public class SecurityConfig {

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        return http
            .authorizeRequests()
                .antMatchers("/swagger-ui/**").permitAll()
                .anyRequest().authenticated()
            .and()
                .formLogin()
                .and()
                .httpBasic();
    }
}

结论

通过集成Swagger，Spring Boot应用可以自动生成API文档，极大地提高了API的可维护性和易用性。本文介绍了如何在Spring Boot中添加Swagger依赖、配置Swagger、使用Swagger注解以及配置Swagger UI。此外，还介绍了如何配置全局异常处理和集成Spring Security来保护API文档。

本文著作权归聚娃科技微赚淘客系统开发者团队，转载请注明出处！