Spring Boot
整合 Swagger 的详细教程如下：
### 安装
Swagger
先下载
Swagger，然后完成安装操作，不过引用中未提及具体的下载
和安装步骤，一般在 Spring Boot 项目里可通过在 `pom.xml` 中添加
Swagger 相关依赖来完成安装，例如添加
Swagger2
和 Swagger UI 的依赖：
```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>
```
### 使用
Swagger
1. **编写接口**：在 Spring Boot 项目里编写 RESTful 接口，示例代码如下：
```java
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
@RequestMapping("/
api")
public class HelloController {
@GetMapping("/hello")
public String hello() {
return "Hello,
Swagger!";
}
}
```
2. **启用
Swagger**：创建一个
配置类来启用
Swagger，示例代码如下：
```java
import org.springframework.context.annotation.Bean;
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.Enable
Swagger2;
@Configuration
@Enable
Swagger2
public class
SwaggerConfig {
@Bean
public Docket
api() {
return new Docket(DocumentationType.
SWAGGER_2)
.select()
.
apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
.paths(PathSelectors.any())
.build()
.
apiInfo(
apiInfo());
}
private
ApiInfo
apiInfo() {
return new
ApiInfoBuilder()
.title("Spring Boot
Swagger API")
.description("
API documentation for Spring Boot application")
.version("1.0.0")
.build();
}
}
```
3. **查看接口
文档**：启动 Spring Boot 项目，在浏览器中访问 `http://localhost:8080/
swagger-ui.html`（如果使用
Swagger2） 或者 `http://localhost:8080/doc.html`（如果使用
Swagger BootstrapUI），就能查看生成的接口
文档 [^2]。
### 高级使用
1. **
描述数据模型**：借助
Swagger 的注解（如 `@
ApiModel`
和 `@
ApiModelProperty`）来
描述数据模型，示例代码如下：
```java
import io.
swagger.annotations.
ApiModel;
import io.
swagger.annotations.
ApiModelProperty;
@
ApiModel(description = "User model")
public class User {
@
ApiModelProperty(value = "User ID", example = "1")
private Long id;
@
ApiModelProperty(value = "User name", example = "John Doe")
private String name;
// Getters and setters
}
```
2. **
描述枚举类型**：使用 `@
ApiModel`
和 `@
ApiModelProperty` 注解
描述枚举类型，示例代码如下：
```java
import io.
swagger.annotations.
ApiModel;
import io.
swagger.annotations.
ApiModelProperty;
@
ApiModel(description = "User role")
public enum UserRole {
@
ApiModelProperty(value = "Admin role")
ADMIN,
@
ApiModelProperty(value = "User role")
USER
}
```
3. **
描述响应参数**：使用 `@
ApiResponse` 注解
描述响应参数，示例代码如下：
```java
import io.
swagger.annotations.
Api;
import io.
swagger.annotations.
ApiOperation;
import io.
swagger.annotations.
ApiResponse;
import io.
swagger.annotations.
ApiResponses;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@
Api(tags = "User
API")
@RestController
@RequestMapping("/
api/users")
public class UserController {
@
ApiOperation(value = "Get user by ID")
@
ApiResponses(value = {
@
ApiResponse(code = 200, message = "Success", response = User.class),
@
ApiResponse(code = 404, message = "User not found")
})
@GetMapping("/{id}")
public User getUserById(Long id) {
// Implementation
return null;
}
}
```
### 进阶使用
1. **
配置全局参数**：若使用
Swagger BootstrapUI，可在“
文档管理”中增加全局参数，包含添加 header 参数 [^3]。
2. **
配置安全协议**：可在
Swagger 中
配置安全协议，如 OAuth2 等。
3. **
配置安全上下文**：
配置安全上下文以确保接口的安全性。
4. **
配置忽略参数**：
配置忽略某些不需要显示的参数。
###
整合 Spring Security 时的注意事项
在 Spring Boot
整合 Spring Security
和 Swagger 时，需要
配置拦截的路径
和放行的路径，要放行以下几个路径：
```java
.antMatchers("/
swagger**/**").permitAll()
.antMatchers("/webjars/**").permitAll()
.antMatchers("/v2/**").permitAll()
.antMatchers("/doc.html").permitAll()
```
如果使用了 bootstarp 的
Swagger UI 界面，需添加最后一个路径 [^1]。
最低0.47元/天 解锁文章
扫一扫
2201
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
