三分钟快速掌握Swagger入门技巧

现在开发,很多采用前后端分离的模式,前端只负责调用接口,进行渲染,前端和后端的唯一联系,变成了API接口。因此,API文档变得越来越重要。swagger是一个方便我们更好的编写API文档的框架,而且swagger可以模拟http请求调用。

大部分采取的方式:Vue + SpringBoot,Vue通过js渲染页面,后端把数据传递给js,早期前端只负责写页面,然后把写好的HTML页面给后端,后端使用模板引擎(Jsp,Thymeleaf、 freemarker)进行开发。

前后端分离的好处:各自开发,相对独立,松耦合,前后端通过API进行交互,后端提供接口给前端,前端去调用该接口,但可能会导致前后端团队人员不能做到及时协商,出现一些问题。解决方式:早期使用实时更新文档,但非常繁琐,后来又使用postman来进行一些测试。

swagger是目前最流行的Api框架,官网:https://swagger.io/

springboot中集成swagger使用步骤:

1.创建springboot工程,然后导入依赖

<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>

2.创建配置类

@Configuration
@EnableSwagger2//开启Swagger2
public class SwaggerConfig {

}

然后启动测试运行,访问:http://localhost:8080/swagger-ui.html,看到如下页面:
在这里插入图片描述
3.手动配置实例,修改SwaggerConfig配置类

package com.qf.swagger.config;

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;

@Configuration
@EnableSwagger2//开启Swagger2
public class SwaggerConfig {

//配置Swagger的Bean实例
@Bean
public Docket swaggerSpringMvcPlugin() {

return new Docket(DocumentationType.SWAGGER_2)

.apiInfo(apiInfo());

}


//配置API的基本信息(会在http://项目实际地址/swagger-ui.html页面显示)

private ApiInfo apiInfo() {

return new ApiInfoBuilder()

.title("测试API文档标题")

.description("测试api接口文档描述")

.termsOfServiceUrl("http://www.baidu.com")

.version("1.0")

.build();

}

}

然后再次重启测试运行:
在这里插入图片描述4.创建实体类

package com.qf.swagger.entity;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel("用户实体类")
public class User {

@ApiModelProperty("用户名")
private String username;

@ApiModelProperty("密码")
private String password;

public String getUsername() {
return username;
}

public void setUsername(String username) {
this.username = username;
}

public String getPassword() {
return password;
}

public void setPassword(String password) {
this.password = password;
}
}

5.创建controller

package com.qf.swagger.controller;
import com.qf.swagger.entity.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

//@Api(description = "用户接口")
@Api(tags = "用户接口")
@RestController
public class UserController {

@ApiOperation("添加用户")
@PostMapping("/add")
public User add(@RequestParam @ApiParam("用户名") String username,@ApiParam("密码") String password){

return new User();
}

@ApiOperation("修改用户")
@PostMapping("/update")
public String update(){
return "修改";
}

@ApiOperation("删除用户")
@GetMapping("/delete")
public Boolean delete(@RequestParam @ApiParam("用户编号") Integer id){
return true;
}

@ApiOperation("查询用户")
@RequestMapping("/query")
public User query(){

User user = new User();
user.setUsername("jack");
user.setPassword("1234");
return user;
}
}

6.修改SwaggerConfig配置类

package com.qf.swagger.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 {

//配置Swagger的Bean实例
@Bean
public Docket swaggerSpringMvcPlugin() {

return new Docket(DocumentationType.SWAGGER_2)

.apiInfo(apiInfo())

.groupName("yangl")//分组名称(可以创建多个Docket就有多个组名)

.enable(true)//enable表示是否开启Swagger

.select()

//RequestHandlerSelectors指定扫描的包

.apis(RequestHandlerSelectors.basePackage("com.qf.swagger.controller"))

.build();

}


//配置API的基本信息(会在http://项目实际地址/swagger-ui.html页面显示)
private ApiInfo apiInfo() {

return new ApiInfoBuilder()

.title("测试API文档标题")

.description("测试api接口文档描述")

.termsOfServiceUrl("http://www.baidu.com")

.version("1.0")

.build();
}
}

运行springboot的启动类,访问:http://localhost:8080/swagger-ui.html#/
在这里插入图片描述swagger可以完全替代postman测试工具,进行对你编写的接口进行测试
在这里插入图片描述在这里插入图片描述swagger通过注解表明该接口会生成文档,包括接口名、请求方法、参数、返回信息

@Api:修饰整个类,描述Controller的作用
@ApiOperation:描述一个类的一个方法,或者说一个接口
@ApiModel:用对象来接收参数 ,修饰类
@ApiModelProperty:用对象接收参数时,描述对象的一个字段
@ApiResponse:HTTP响应其中1个描述
@ApiResponses:HTTP响应整体描述,一般描述错误的响应
@ApiIgnore:使用该注解忽略这个API
@ApiError :发生错误返回的信息
@ApiParam:单个参数描述
@ApiImplicitParam:一个请求参数,用在方法上
@ApiImplicitParams:多个请求参数

  • 0
    点赞
  • 0
    收藏
    觉得还不错? 一键收藏
  • 0
    评论
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值