Swagger
2025-11-20 21:17:20 0 举报AI智能生成
Swagger是一款简单但功能强大的REST API的开发工具。它允许用户描述API的功能，通过API生成具有交互性的文档，并为API的使用提供一个测试平台。Swagger的核心内容包括API的路径、操作、输入参数、输出格式以及可能的错误代码等。通过集成Swagger，开发者可以利用其自动生成的、人性化的API文档，提高API的可视化程度，优化开发和调试流程。 这种描述还支持OpenAPI标准（前称Swagger规范），可以生成多种编程语言的服务器存根和客户端SDK，极大地增强了API的生产效率和互操作性。同时，Swagger还支持各种自定义扩展，比如安全性定义、错误处理、中间件配置等，使得它可以适应各种复杂的应用场景。总体而言，Swagger是现代化API设计、构建、文档化和使用流程不可或缺的一部分。
作者其他创作
大纲/内容
创建由来，解决了什么问题？
Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。
具体实现：接口文档在线生成，功能测试。
应用主流
- Swagger-tools:提供各种与Swagger进行集成和交互的工具。例如模式检验、Swagger 1.2文档转换成Swagger 2.0文档等功能。
- Swagger-core: 用于Java/Scala的的Swagger实现。与JAX-RS(Jersey、Resteasy、CXF...)、Servlets和Play框架进行集成。
- Swagger-js: 用于JavaScript的Swagger实现。
- Swagger-node-express: Swagger模块，用于node.js的Express web应用框架。
- Swagger-ui：一个无依赖的HTML、JS和CSS集合，可以为Swagger兼容API动态生成优雅文档。
- Swagger-codegen：一个模板驱动引擎，通过分析用户Swagger资源声明以各种语言生成客户端代码。
注解语法
controller类上
@Api(value="用户controller",tags={"用户操作接口"})
controller方法
@ApiOperation(value="获取用户信息",tags={"获取用户信息copy"},notes="注意问题点")
@ApiParam(name="id",value="用户id",required=true) Long id
＠ApiIgnore()用于类或者方法上，可以不被swagger显示在页面上
@ApiImplicitParams({
@ApiImplicitParam(name="name",value="用户名",dataType="string", paramType = "query",example="xingguo"),
@ApiImplicitParam(name="id",value="用户id",dataType="long", paramType = "query")})
@ApiImplicitParam(name="name",value="用户名",dataType="string", paramType = "query",example="xingguo"),
@ApiImplicitParam(name="id",value="用户id",dataType="long", paramType = "query")})
@ApiResponses({ @ApiResponse(code = 200, message = "OK", response = UserDto.class) })
实体类上
@ApiModel(value="user对象",description="用户对象user")
@ApiModelProperty(value="用户名",name="username",example="xingguo")
@RequestBody @ApiParam(name="用户对象",value="传入json格式",required=true) User user
在项目中引入
pom文件，引入jar包
<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>
<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(集成到spring,配置文档路径等)
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
// 指定构建api文档的详细信息的方法：apiInfo()
.apiInfo(apiInfo())
.select()
// 指定要生成api接口的包路径也可以指定具体路径
.apis(RequestHandlerSelectors.any())
// 访问路径下面的接口
.paths(PathSelectors.ant("/yhxx/**"))
//使用了 @ApiOperation 注解的方法生成api接口文档
//.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
.paths(PathSelectors.any())
//可以根据url路径设置哪些请求加入文档，忽略哪些请求
.build()
.groupName("用户管理"); // 分组管理可以与那个访问路径结合使用。
}
/**
* 设置api文档的详细信息
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
// 标题
.title("Spring Boot集成Swagger2")
// 接口描述
.description("swagger")
// 联系方式
.contact("联系方式")
// 版本信息
.version("1.0")
// 构建
.build();
}
}
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
// 指定构建api文档的详细信息的方法：apiInfo()
.apiInfo(apiInfo())
.select()
// 指定要生成api接口的包路径也可以指定具体路径
.apis(RequestHandlerSelectors.any())
// 访问路径下面的接口
.paths(PathSelectors.ant("/yhxx/**"))
//使用了 @ApiOperation 注解的方法生成api接口文档
//.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
.paths(PathSelectors.any())
//可以根据url路径设置哪些请求加入文档，忽略哪些请求
.build()
.groupName("用户管理"); // 分组管理可以与那个访问路径结合使用。
}
/**
* 设置api文档的详细信息
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
// 标题
.title("Spring Boot集成Swagger2")
// 接口描述
.description("swagger")
// 联系方式
.contact("联系方式")
// 版本信息
.version("1.0")
// 构建
.build();
}
}
注意跨域问题
具体使用，注解标识
0 条评论
下一页
