您现在的位置是：首页 > 文章详情

springboot集成swagger2构建RESTful API

日期：2018-11-29点击：586收藏

在开发过程中,有时候我们需要不停的测试接口,自测,或者交由测试测试接口,我们需要构建一个文档,都是单独写,太麻烦了,现在使用springboot集成swagger2来构建RESTful API文档,可以在访问接口上,直接添加注释

先介绍一下开发环境:

jdk版本是1.8

springboot的版本是1.4.1

开发工具为 intellij idea

我们先引入swagger2的jar包,pom文件引入依赖如下:

<dependency>    <groupId>io.springfox</groupId>    <artifactId>springfox-swagger2</artifactId>    <version>2.6.1</version> </dependency> <dependency>    <groupId>io.springfox</groupId>    <artifactId>springfox-swagger-ui</artifactId>    <version>2.6.1</version> </dependency>

接下来,我们构建swagger2的配置类,代码如下:

//注解开启 swagger2 功能 @EnableSwagger2 //注解标示,这是一个配置类,@Configuation注解包含了@Component注解 //可以不用在使用@Component注解标记这是个bean了, @Configuration public class Swagger2 { /**  * 通过 createRestApi函数来构建一个DocketBean  * 函数名,可以随意命名,喜欢什么命名就什么命名  */ @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo())//调用apiInfo方法,创建一个ApiInfo实例,里面是展示在文档页面信息内容 .select() //控制暴露出去的路径下的实例 //如果某个接口不想暴露,可以使用以下注解 //@ApiIgnore 这样,该接口就不会暴露在 swagger2 的页面下 .apis(RequestHandlerSelectors.basePackage("com.example")) .paths(PathSelectors.any()) .build(); }     //构建 api文档的详细信息函数 private ApiInfo apiInfo() { return new ApiInfoBuilder() //页面标题 .title("Spring Boot 测试使用 Swagger2 构建RESTful API") //创建人 .contact("贺小五") //版本号 .version("1.0") //描述 .description("API 描述") .build(); } }

swagger2的配置类已经配置好了,下面,我们就在主函数里面随意写一些接口吧

@SpringBootApplication(scanBasePackages = {"com"}) //该注解包含了@Controller和@ResponseBody两个注解 @RestController public class DemoApplication{ public static void main(String[] args) { SpringApplication.run(DemoApplication.class, args); }     /**     * 以下函数的注释,不增加注解了,将在下面统一做描述     */ @ApiOperation(value = "测试post请求",notes="注意事项") @ApiImplicitParam(dataType = "User",name = "user",value = "用户信息",required = true) @RequestMapping(value = "/testPost",method = RequestMethod.POST) public String testPost(@RequestBody User user){ return "success"; } @ApiOperation(value = "测试get请求",notes="注意事项") @ApiImplicitParam(name = "id",value = "用户id",dataType = "String",paramType = "path") @RequestMapping(value = "/testGet/{id}",method = RequestMethod.GET) public String testGet(@PathVariable String id){ return id; } @ApiOperation(value = "测试组合注解",notes="注意事项") @ApiImplicitParams({ @ApiImplicitParam(dataType = "User",name = "user",value = "用户信息",required = true,paramType = "body"), @ApiImplicitParam(dataType = "string",name = "id",value = "用户id",required = true,paramType = "path") }) @RequestMapping(value = "/joinAnnotation/{id}",method = RequestMethod.POST) public User joinAnnotation(@PathVariable String id,@RequestBody User user){ return user; } @ApiIgnore public String testIgnore(){ return "success"; } }

写好controller后,我们可以访问以下地址:http://localhost:8080/swagger-ui.html,如果你没引入swagger2依赖,你是访问不了的..然后你会得到一个如下页面

images/5sYsNJCMwQa4Ain4mTJEGTHwaJpMFdnX.png

上面的页面,就是swagger2里面的页面,可以发现, apiInfo里面设置的内容在左边展示出来了,demo-application其实就是controller的类名,右边有三个按钮,分别是 Show/Hide,List Opertions和Expand Operations,三个按钮都可以打开,类下的接口,点击后,会得到如下一个效果页面:

images/A7bYHtMpSexKipTc8xiGwzNcj8T7SmmC.png