Swagger介绍
（1）简介 丝袜哥
Swagger 是一个规范完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务(https://swagger.io/)。 它的主要作用是：
-
使得前后端分离开发更加方便，有利于团队协作
-
接口的文档在线自动生成，降低后端开发人员编写接口文档的负担
-
功能测试
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,
结果如下：