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

springboot集成swagger2构建RESTful API

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

在开发过程中,有时候我们需要不停的测试接口,自测,或者交由测试测试接口,我们需要构建一个文档,都是单独写,太麻烦了,现在使用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