文章目录

• Swagger介绍
• • （1）简介 丝袜哥
  • （2）SpringBoot集成Swagger
  • （3）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属性详解：

• 我们在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,

结果如下：