1、前言
我们写的restful接口是给别人用的,但是,这个接口在怎么用?资源路径在哪?参数传什么?。。。。。。
这么多信息写接口的人是需要提供给接口使用者的。一种方式是写文档,大家共享文档,但是这样还是比较麻烦,需要不断的更新文档,维护文档,还需要确保文档及时的分享给我们的小伙伴。对于这个问题,我们伟大的先驱者已经想到解决的方法,那就是一个非常便捷的神器——swagge。通过这个工具,我们可以直接在代码中将接口信息使用方法、接口的功能等等信息直接写在代码中,对外提供一个一目了然的界面,用起来爽的不要不要的。
好了,废话不多讲,我们来看一下怎么在spring-boot中如何集成swagge这个神器吧
2、准备工作
pom文件需要添加依赖
<properties> <java.version>1.8</java.version> <springfox.swagger.version>2.5.0</springfox.swagger.version> </properties>
<!-- Swagger begin --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>${springfox.swagger.version}</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>${springfox.swagger.version}</version> </dependency> <!-- Swagger end -->在我们的app运行主类的同级目录下创建swagge配置类
@Configuration @EnableSwagger2 public class Swagger2 { @Bean public Docket createRestApi(){ return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.sonsf.learn")) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo(){ return new ApiInfoBuilder() .title("restful学习接口") .description("学习用spring-boot学习写restful接口") .termsOfServiceUrl("https://github.com/learnerfan/spring-boot-restful") .contact("代码狗") .version("v1.0") .build(); } }代码的整体结构如下
然后run一下即可
3、效果展示
访问http://localhost:7101/swagger-ui.html
怎么样,有个界面用起来是不是要比简单的测试工具要爽很多?
4、接口信息书写
@RequestMapping(value = "/hello",method = RequestMethod.GET) @ApiOperation(value = "问候接口",notes = "这个接口通过输入一个名字,返回hell+name信息,内容放在message对象中") public JSONObject greet(@ApiParam(value = "名字")@RequestParam()String name){ JSONObject response = new JSONObject(); response.put("message","hello"+" "+name); return response; }我们通过@ApiOperation注解来添加我们对接口信息的描述
例如接口的名字是:问候接口,备注,note=""
通过@ApiParm(value="姓名")来增加对参数的描述
其中note中的信息支持html元素的识别,例如备注信息过多,需要换行,我们可以再内容中增加一个</br>换行标志
5、关于swagge配置类中的信息可以写在配置文件中,方便我们及时修改
好了,关于spring-boot集成swagge我们介绍到这里,更多的规范类的东东,需要小伙伴们自己在实践的过程中慢慢摸索吧
代码地址:https://github.com/learnerfan/spring-boot-restful.git