###
Swagger API 使用指南
Swagger 是一种用于设计、构建、记录和使用 RESTful Web 服务的强大工具集。以下是关于如何使用
Swagger 进行
API 文档生成的相关信息。
#### 一、
Swagger 的基本概念
Swagger 提供了一种标准化的方式来描述 RESTful 接口，通过 Open
API 规范定义接口的行为[^4]。开发者可以通过注解的方式让
Swagger 自动生成详细的
API 文档，并支持在线测试功能。
---
####
二、
Spring Boot 中集成
Swagger
在
Spring Boot 项目中集成
Swagger 主要分为以下几个方面：
1. **引入依赖**
在项目的 `pom.xml` 或 `build.gradle` 文件中添加
Swagger 相关的依赖项。
对于 Maven 构建工具：
```xml
<!
-- Spring Boot 集成
swagger -->
<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>
```
2. **配置
Swagger**
创建一个名为 `
SwaggerConfig.java` 的配置类来初始化
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;
@Configuration
@Enable
Swagger2
public class
SwaggerConfig {
private
ApiInfo
apiInfo
() {
return new
ApiInfoBuilder
()
.title
("示例
API 文档"
) // 设置文档标题
.description
("这是一个简单的
API 示例"
) // 描述
.version
("1.0.0"
) // 版本号
.build
();
}
@Bean
public Docket createRest
Api() {
return new Docket
(DocumentationType.
SWAGGER_2
)
.
apiInfo
(apiInfo
())
.select
()
.
apis
(RequestHandlerSelectors.basePackage
("com.example.controller"
)) // 扫描 Controller 包路径
.paths
(PathSelectors.any
()) // 路径过滤器
.build
();
}
}
```
3. **运行应用并访问文档**
启动应用程序后，默认情况下可以访问以下地址查看自动生成的
API 文档界面：
- JSON 格式的
API 文档：`http://localhost:8080/v2/
api-docs`
- Swagger UI 页面：`http://localhost:8080/
swagger-ui.html`
---
#### 三、静态文档生成
如果需要将动态生成的
API 文档导出为静态文件以便离线查阅，则可以借助 Asciidoctor 工具或其他插件完成此操作[^5]。具体方法如下：
1. 修改根目录下的 `asciidoc` 文件结构，按照指定模板组织内容。
2. 添加类似以下的内容到 `.adoc` 文件中：
```plaintext
include::{generated}/overview.adoc[]
include::{generated}/definitions.adoc[]
include::{generated}/paths.adoc[]
```
3. 将生成的 HTML 文件打包分发给相关人员。
---
#### 四、其他注意事项
- 如果希望禁用某些敏感接口不被暴露出来，可以在 `Docket` 配置中加入更精确的选择条件[^3]。
- 当前版本可能存在兼容性问题，请确保所使用的库版本一致以减少潜在冲突风险[^4]。
---
###
本文详细介绍了Swagger API文档中@ApiIgnore注解的使用方法及效果。通过对比有无注解的差异，阐述了如何利用该注解来排除不希望展示在文档中的API接口。
扫一扫
1506
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
