0
点赞
收藏
分享

微信扫一扫

SpringBoot整合Swagger

文章目录

Swagger介绍

(1)简介 丝袜哥

Swagger 是一个规范完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务(https://swagger.io/)。 它的主要作用是:

  1. 使得前后端分离开发更加方便,有利于团队协作

  2. 接口的文档在线自动生成,降低后端开发人员编写接口文档的负担

  3. 功能测试

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

    单快捷的使用Swagger。

(2)SpringBoot集成Swagger

在这里插入图片描述

  • 第一步:引入依赖,在heima-leadnews-common模块中引入该依赖
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
</dependency>
  • 第二步:在heima-leadnews-common工程的swagger包中添加一个配置类
package com.heima.common.swagger;

import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
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;

@Configuration
@EnableSwagger2   // 开启Swagger功能
public class SwaggerConfiguration {

   @Bean
   public Docket buildDocket() {
      return new Docket(DocumentationType.SWAGGER_2)
              .apiInfo(buildApiInfo())
              .select()
              // 要扫描的API(Controller)基础包
              .apis(RequestHandlerSelectors.basePackage("com.heima"))	//存在多个微服务
              .paths(PathSelectors.any())
              .build();
   }

   /**
    * 构建Api信息
    * @return
    */
   private ApiInfo buildApiInfo() {
      Contact contact = new Contact("黑马程序员","","");		//名字 url 邮箱
      return new ApiInfoBuilder()
              .title("黑马头条-平台管理API文档")		//api文档的标题
              .description("平台管理服务api")
              .contact(contact)			//创建人信息
              .version("1.0.0").build();
   }
}

  • 第三步:在heima-leadnews-media模块中的config包中添加配置类
package com.heima.media.config;

import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;

@Configuration
@ComponentScan("com.heima.common.swagger")
public class SwaggerConfig {
}

(3)Swagger常用注解

在Java类中添加Swagger的注解即可生成Swagger接口文档,常用Swagger注解如下:

@Api:修饰整个类,描述Controller的作用

tags 指定名称

@ApiOperation:描述一个类的一个方法,或者说一个接口

value 指定名称 notes 添加备注

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

@ApiModel:用对象来接收参数

@ApiModelProperty:用对象接收参数时,描述对象的一个字段

value 指定字段名称

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

@ApiResponses:HTTP响应整体描述

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

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

@ApiImplicitParam:一个请求参数

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

  • @ApiImplicitParam属性详解:
属性取值作用
paramType查询参数类型
path以地址的形式提交数据
query直接跟参数完成自动映射赋值
body以流的形式提交 仅支持POST
header参数在request headers 里边提交
form以form表单的形式提交 仅支持POST
dataType参数的数据类型 只作为标志说明,并没有实际验证
Long
String
name接收参数名
value接收参数的意义描述
required参数是否必填
true必填
false非必填
defaultValue默认值
  • 我们在heima-leadnews-media模块中的controller包中WmChannelController中添加Swagger注解,代码如下所示:
@RestController
@RequestMapping("/api/v1/channel")
@Api(tags = "频道管理API")
public class WmChannelController {

    // 注入服务接口
    @Autowired
    private IWmChannelService wMChannelService;

    /**
     * 根据名称模糊查询分页列表
     *
     * @param dto
     * @return
     */
    @PostMapping("/list")
    @ApiOperation(value = "根据名称模糊查询分页列表", notes = "author:syl")  // value指名称  notes 备注
    @ApiImplicitParam(name = "dto", value = "查询对象", required = true, dataType = "ChannelDto")
    public ResponseResult listByName(@RequestBody ChannelDto dto) {
        return wMChannelService.listByName(dto);
    }

}
  • ChannelDto
package com.heima.media.dto;

import com.heima.common.dto.PageRequestDto;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import lombok.EqualsAndHashCode;

@Data
@EqualsAndHashCode(callSuper = true)
public class ChannelDto extends PageRequestDto {

    /**
     * 频道名称
     */
    @ApiModelProperty(value = "频道名称")
    private String name;
}

  • 启动media微服务,访问地址:http://localhost:9001/swagger-ui.html

在这里插入图片描述

查询:
在这里插入图片描述

先点击Try it out 输入参数,然后点击Execute,
在这里插入图片描述
结果如下:在这里插入图片描述

举报

相关推荐

0 条评论