前言:
作为标标准准的后台开发攻城狮,在于前端交互给其提供接口的时候,是不是要给其准备接口文档?是不是在和他联调之前首先要自测通过呢?是不是自测之前要写接口调用(比如postman)呢?作为一个负责滴、追求向上滴工程师,那这些肯定是要做的。事情都要做,可做事的方式不同,结果和效率也不同,那么下面和大家分享一下springboot项目中提供的接口如何方便快捷提供一种自测,甚至是直接给接口测试人员测试的方式,那就是整合进去seagger2.用了还想用的第三方插件吧,
申明:
我不喜欢文章很复杂,追求简而美观的实用性,但是为了需要的伙伴能够直接一步到位,绝对可用,所以直接粘贴的核心代码,方便你们复制过去,因此给文章增加了看起来不太友好的复杂度。
开发环境:
1、添加依赖
这里默认我们已使用的maven项目,否则的话请自行下载依赖相关的java包也一样,项目引入以下依赖:
<!– https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 –>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency><!– https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui –>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
2、添加配置类
package cn.seally.community.config;
import static com.google.common.base.Predicates.or;
import static springfox.documentation.builders.PathSelectors.regex;import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;import com.google.common.base.Predicate;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;/**
* @Description swagger在线接口插件配置类
* @Date 2019年8月31日
* @author seallydeng
*/
@Configuration
@EnableSwagger2 //开启在线接口文档
public class SwaggerConfig {
/**
* @Description
* @Date 2019年8月31日
* @author seallydeng
* @return
*/
@Bean
public Docket controllerApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(new ApiInfoBuilder()
.title(“标题:Seally Web 接口文档”)//标题
.description(“本系统接口主要包括xxx、yyy等功能模块”)//描述
.contact(new Contact(“dningcheng”, “http://www.xxx.com/web”, “dningcheng@163.com”))
.version(“1.0.0”)//版本号
.build())
.select()
.apis(RequestHandlerSelectors.basePackage(“cn.seally.community.controller”))//配置扫描的控制器类包
.paths(paths())//配置符合指定规则的路径接口才生成在线接口,用于定制那些接口在ui中展示
.build();
}
@SuppressWarnings(“unchecked”)
private Predicate<String> paths() {
return or(regex(“/user/api/.*?”));
}
}
3、控制器以注解方式增加接口描述信息
package cn.seally.community.controller;
import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.PutMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;import cn.seally.community.common.ApiResponse;
import cn.seally.community.model.base.SystemUser;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;/**
* @Description 用于演示swagger在线接口文档的控制器
* @Date 2019年8月31日
* @author seallydeng
*/
@Api(tags={“系统首页热点图相关接口”}) //标注在类上:用以备注接口组名称
@RestController
@RequestMapping(“/demo”)
public class DemoController {
@ApiOperation(value=”获取用户信息”,notes=”username是唯一属性,单个用户可直接通过username获取”) //标注在方法:用以备注接口描述
@GetMapping(value=”/user/query”)
public ApiResponse<String> getUserInfo(String username){
return ApiResponse.success(“获取信息通过”);
}
@PostMapping(value=”/user/save”,produces=”application/json”)
public ApiResponse<String> saveUserInfo(@RequestBody SystemUser user){
return ApiResponse.success(“保存用户信息成功”);
}
@PutMapping(value=”/user/update”,produces=”application/json”)
public ApiResponse<String> updateUserInfo(@RequestBody SystemUser user){
return ApiResponse.success(“修改用户信息成功”);
}
@DeleteMapping(value=”/user/delete/{username}”,produces=”application/json”)
public ApiResponse<String> deleteUserInfo(@PathVariable(“username”) String username){
return ApiResponse.success(“删除用户信息成功”);
}
}
4、启动项目,进行访问
在浏览器输入访问路径即可访问,通常如果项目没有配置路径则直接使用:http://ip:port/swagger-ui.html 即可访问,如果springboot配置了项目路径如:
那么访问的路径名则为:http://ip:port/seally-community-web/swagger-ui.html
如果项目正常,则可看到如下界面:
让我们点开一个方法看下:
界面太大所以只截取部分,这里我们只需要输入请求参数,点击执行,就可以看奥执行结果如:
同时右边还有下载按钮可以直接下载到一个json格式的返回值。
通常各种方法在swagger的接口界面都会为我们对应生成参数,只需要填写值就可直接执行请求,以下是post请求,以application/json方式发起请求的示例:
总结:
swagger2是不是很好用了,上面只演示了觉得用得上的注解,当然它还有一系列的注解帮助我们对接口和入参进行详细说明比如:
-
@ApiImplicitParams:用在请求的方法上,表示一组参数说明
-
@ApiImplicitParam:用在@ApiImplicitParams注解中,代表某一个具体参数,用于单个参数的各个信息说明
-
@ApiResponses:用在请求的方法上,表示一组响应
-
@ApiResponse:用在@ApiResponses中,表示响应的某个具体参数,用于对具体参数的各个方面进行说明
-
@ApiModel:用于响应类上,表示一个返回响应数据的信息
-
@ApiModelProperty:和@ApiModel搭配使用,用在响应类的属性上,描述响应类的属性信息
这些注解,可根据需要使用,通常只要参数定义的好,有具体的语义,我觉得不需要这么详细的备注,额外增加写注解的工作量。
怎么样,是不是很简单呢,有需要的小伙伴儿们,赶快试试吧,如果觉得好用,不妨帮我点个赞,鼓励鼓励我在分享的路上,永不止步哦…!
原创文章,作者:奋斗,如若转载,请注明出处:https://blog.ytso.com/tech/opensource/193700.html