首先要说一下为啥要使用swagger,兄弟们都知道,如今俺们程序员最不喜欢的四件事就是“写文档,写注释,别人不写文档,别人不写注释”
试想一下,当你累的一批,写完了程序并且调试完bug之后,这时前端兄弟找你写一下接口文档,此时你的内心。。。。
这时swagger就派上用场了,来一起看看怎么使用吧。
这里先介绍一下swagger部分的注解,基本上这些就够用了。
Controller
注解 | 可设置属性 | 使用说明 |
---|---|---|
@Api | tags | 标注在controller之上,比较常用;表明该controller的作用,显示在接口文档中 |
@ApiOperation | value | 标注在具体的接口方法上,表明方法的作用,展示在接口文档中 |
@ApiOperation | notes | 标注在具体的接口方法上,表明方法的具体作用,展示在接口文档中 |
Model
注解 | 可设置属性 | 使用说明 |
---|---|---|
@ApiModel | value | 标注在class之上,表明实体类的信息,展示在接口文档中 |
@ApiModelProperty | value | 标注在属性之上,表明属性的信息,展示在接口文档中 |
有了上面这些注解就可以使用swagger制作接口文档了
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
package com.xiaow.swagger.config;
import org.springframework.beans.factory.annotation.Value;
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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
1. swagger配置类
*/
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
//是否开启 (true 开启 false隐藏。生产环境建议隐藏)
//.enable(false)
.select()
//扫描的路径包,设置basePackage会将包下的所有被@Api标记类的所有方法作为api
.apis(RequestHandlerSelectors.basePackage("com.xiaow.swagger.controller"))
//指定路径处理PathSelectors.any()代表所有的路径
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
//设置文档标题(API名称)
.title("解放后端程序员的神器")
//文档描述
.description("和前端交互,不可能")
//服务条款URL
//这里填的我的个人博客地址,欢迎各位大佬
.termsOfServiceUrl("https://xiaow123.gitee.io/hexo_blog")
//版本号
.version("1.0.0")
.build();
}
}
Controller
import com.xiaow.swagger.model.TestModel;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiResponse;
import io.swagger.annotations.ApiResponses;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
@Api(tags = "测试接口")
@RestController
public class TestController {
@ApiOperation(value="更新用户详细信息", notes="根据url的id来返回对象")
@GetMapping("/test")
public TestModel test(@RequestParam(required = true,value = "序号") Integer id){
return new TestModel()
.setEmail("123@xx.com")
.setId(id)
.setName("xiaow");
}
}
Model
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import lombok.experimental.Accessors;
import java.io.Serializable;
@Data
@ApiModel(value = "测试类")
@Accessors(chain = true)
public class TestModel implements Serializable {
@ApiModelProperty(value = "序号")
private Integer id;
@ApiModelProperty(value = "姓名")
private String name;
@ApiModelProperty(value = "邮箱")
private String email;
}
到现在为止,我们就简单的使用swagger生成了接口文档,看看成果吧。
启动项目之后,来到默认swagger接口文档,如下图
按照图中红色箭头依次点击就来到了接口测试
输入参数之后点击execute就实现了接口的调用,如下图
箭头处就是返回的内容。
swagger可以帮我们节省一部分写文档的时间,而且很方便前端程序员进行对接,到现在就完成了swagger的基础使用,是不是蛮简单的,快动手试试吧