Swagger2简介
Swagger2 可以快速帮助我们编写最新的API接口文档,再也不用担心开会前仍忙于整理各种资料了,间接提升了团队开发的沟通效率。
常用注解
swagger通过注解声明该接口会生成文档,包括接口名、请求方法、参数、返回信息的等等
注解 | 作用 |
---|---|
@Api | 修饰整个类,描述当前Controller的作用 |
@ApiOperation | 描述一个类的一个方法,或者一个接口 |
@ApiParam | 描述单个参数 |
@ApiModel | 实体类描述 |
@ApiModelProperty | 描述实体类的参数 |
@ApiImplicitParam | 一个请求参数 |
@ApiImplicitParams | 多个请求参数 |
示例:
所需pom依赖
<!-- swagger-ui -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
<!--swagger2 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
<scope>compile</scope>
</dependency>
swagger2 配置类
package org.example.consumer.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration /*标记当前类为配置类,相关配置会在启动时加载*/
@EnableSwagger2 /*启用swagger2相关配置*/
public class SwaggerConfig {
// 创建API应用
@Bean
public Docket restApi(){
return new Docket(DocumentationType.SWAGGER_2)
// 分组名称 如果没有配置 默认是default
.groupName("新建接口")
.apiInfo(apiInfo("疯狂小乐哥", "1.0"))
.select()
// 扫描所有包
.apis(RequestHandlerSelectors.any())
.build();
}
/*
创建该Api的基本信息
这些基本信息会显示在 swagger-ui 界面中
*/
private ApiInfo apiInfo(String title, String version) {
return new ApiInfoBuilder()
// 标题
.title(title)
// 版本号
.version(version)
// 网址
.description("更多请关注: https://blog.csdn.net/weixin_48037689spm=1010.2135.3001.5421")
.termsOfServiceUrl("https://blog.csdn.net/weixin_48037689?spm=1010.2135.3001.5421")
.build();
}
}
controller类
@Api("时间Controller")
@RestController
public class TimeController {
private ITimeService timeService;
@ApiOperation("获取当前时间")
@PostMapping("/time")
public String time(){
return timeService.getTime().format(DateTimeFormatter.ISO_DATE_TIME);
}
实体类
@ApiModel("用户类")
public class User {
@ApiModelProperty(value = "名字")
public String name;
@ApiModelProperty("年龄")
public Integer age;
public String getName() {
return name;
}
public Integer getAge() {
return age;
}
public void setName(String name) {
this.name = name;
}
public void setAge(Integer age) {
this.age = age;
}
}
swagger-ui界面
地址:http://localhost:端口号/swagger-ui.html
可以测试代码 红线部分为响应