1.引入依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
</dependency>
2.添加配之类
package com.xxx.admin.config;
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
public class SwaggerConfiguration {
@Bean
public Docket buildDocket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(buildApiInfo())
.select()
// 要扫描的API(Controller)基础包
.apis(RequestHandlerSelectors.basePackage("com.xxx"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo buildApiInfo() {
Contact contact = new Contact("PRC","","");
return new ApiInfoBuilder()
.title("XXX-平台管理API文档")
.description("平台管理服务api")
.contact(contact)
.version("1.0.0").build();
}
}
3.controller添加注解
@RestController
@RequestMapping("/api/v1/channel")
@Api(tags = "频道管理",description = "频道管理API")
public class AdChannelController {
@Autowired
private IAdChannelService adChannelService;
@ApiOperation(value = "根据名称分页查询频道列表")
@ApiImplicitParam(name = "dto", value = "频道请求对象", required = true, dataType = "ChannelDto")
@PostMapping("/list")
public PageResult<ChannelDto> findByPage(@RequestBody ChannelDto dto) {
return adChannelService.findByPage(dto);
}
}
@Data
public class ChannelDto extends PageRequestDto {
/**
* 频道名称
*/
@ApiModelProperty("频道名称")
private String name;
}
@Setter
public class PageRequestDto {
@ApiModelProperty(value="每页显示条数",required = true)
protected Integer size;
@ApiModelProperty(value="当前页",required = true)
protected Long page;
public Integer getSize() {
if (this.size == null || this.size <= 0 || this.size > 100) {
setSize(10);
}
return size;
}
public Long getPage() {
if (this.page == null || this.page <= 0) {
setPage(1L);
}
return page;
}
}
4.启动当前程序,访问http://上面启动服务ip:上面启动的服务端口号http://上面启动服务ip:
5.Swagger常用注解
在Java类中添加Swagger的注解即可生成Swagger接口文档,常用Swagger注解如下:
@Api:修饰整个类,描述Controller的作用
@ApiOperation:描述一个类的一个方法,或者说一个接口
@ApiParam:单个参数的描述信息
@ApiModel:用对象来接收参数
@ApiModelProperty:用对象接收参数时,描述对象的一个字段
@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 | 默认值 |