Swagger介绍

最新推荐文章于 2025-08-27 19:17:55 发布

原创最新推荐文章于 2025-08-27 19:17:55 发布 · 154 阅读

0 ·

CC 4.0 BY-SA版权

文章标签：

#java

简介:

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化风格的 Web 服务。它的主要作用是：

使得前后端分离开发更加方便，有利于团队协作
接口的文档在线自动生成，降低后端开发人员编写接口文档的负担
功能测试

Spring已经将Swagger纳入自身的标准，建立了Spring-swagger项目，现在叫Springfox。通过在项目中引入Springfox ，即可非常简单快捷的使用Swagger.

使用步骤 :

引入依赖,在itheima-leadnews模块中引入该依赖

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

导入配置类:

package com.itheima.admin.config;

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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.HashSet;

@Configuration
@EnableSwagger2
public class SwaggerConfiguration {

   @Bean
   public Docket buildDocket() {
      HashSet<String> strings = new HashSet<>();
      strings.add("application/json");

      return new Docket(DocumentationType.SWAGGER_2)
              .apiInfo(buildApiInfo())
              //设置返回值数据类型为json
              .produces(strings)
              .select()
              // 要扫描的API(Controller)基础包
              .apis(RequestHandlerSelectors.basePackage("基础包路径com.it"))
              .paths(PathSelectors.any())
              .build();
   }

   private ApiInfo buildApiInfo() {
      Contact contact = new Contact("程序员","","");
      return new ApiInfoBuilder()
              .title("项目名称-平台管理API文档")
              .description("服务api名称")
              .contact(contact)
              .version("1.0.0").build();
   }
}

Swagger常用注解

@Api(tags = "名称")：修饰整个类，描述Controller的作用  

@ApiOperation：修饰类的一个方法 标识 操作信息 接口的定义

@ApiParam：单个参数的描述信息  

@ApiModel：描述使用到的对象信息

@ApiModelProperty：描述使用到的对象的属性信息

@ApiResponse：HTTP响应其中1个描述  

@ApiResponses：HTTP响应整体描述  

@ApiIgnore：使用该注解忽略这个API  

@ApiError ：发生错误返回的信息  

@ApiImplicitParam：一个请求参数  

@ApiImplicitParams：多个请求参数的描述信息

 @ApiImplicitParam属性：