Swagger

2024-03-24 21:38:49   27  举报





AI智能生成

Swagger是一种开源的Web服务API描述语言和工具集，用于生成、描述、调用和可视化RESTful风格的Web服务。Swagger框架为RESTful API提供了自动生成文档和交互式API控制台的功能，通过读取服务和端点的元数据来定义API，并以简单、直观的UI呈现。此外，Swagger还支持多种格式的API文档导出，如JSON、XML等，可方便地与各种开发工具集成。它简化了Web服务的开发和维护，提高了API的可读性和可理解性，为开发者提供了一种高效的RESTful API设计和开发方式。

Swagger

Java学习

Java框架

Java接口

作者其他创作

大纲/内容

创建由来，解决了什么问题？

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。

具体实现：接口文档在线生成，功能测试。

应用主流

<ol><li>Swagger-tools:提供各种与Swagger进行集成和交互的工具。例如模式检验、Swagger 1.2文档转换成Swagger 2.0文档等功能。</li><li>Swagger-core: 用于Java/Scala的的Swagger实现。与JAX-RS(Jersey、Resteasy、CXF...)、Servlets和Play框架进行集成。</li><li>Swagger-js: 用于JavaScript的Swagger实现。</li><li>Swagger-node-express: Swagger模块，用于node.js的Express web应用框架。</li><li>Swagger-ui：一个无依赖的HTML、JS和CSS集合，可以为Swagger兼容API动态生成优雅文档。</li><li>Swagger-codegen：一个模板驱动引擎，通过分析用户Swagger资源声明以各种语言生成客户端代码。</li></ol>

注解语法

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")})

@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>

配置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();     } }

注意跨域问题

具体使用，注解标识