在spring-boot中使用swagger2来构建RESTful API文档

在spring-boot中使用swagger2来构建RESTful API文档,可以让使用者很清晰的看到相关接口的出入参,并且方便测试

使用步骤:

1:在pom文件中引入swagger2的依赖

<!-- swagger2 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.2.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.2.2</version>
</dependency>
<!-- swagger2 -->
2:在Application.java的同级下新建swagger2的配置类



swagger2配置类如下

package com.sh.daniel;

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;

/**
* Swagger2的配置类
*
* @author Daniel
*
*/

@Configuration //让Spring来加载该类配置
@EnableSwagger2 //开启Swagger2
public class Swagger2 {

public Docket api(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//指定包路径,此路径下的接口会在Swagger2中显示,如果要忽略的话加上注解(@ApiIgnore)
.apis(RequestHandlerSelectors.basePackage("com.sh.daniel.controller"))
.paths(PathSelectors.any())
.build();
}

//api展示的相关信息
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
//标题
.title("在spring-boot中使用Swagger2构建restful api")
//描述
.description("关于用户操作的相关接口信息")
//联系人
.contact("Daniel")
//版本号
.version("1.0")
.build();
}

}
3:编写相关的controller类
package com.sh.daniel.controller;

import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;
import com.sh.daniel.domain.User;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;

/**
* 用户操作相关接口
*
* @author Daniel
*
*/
@RestController
@RequestMapping("/user")
public class UserController {

/**
* 新建用户
*
* @param user
* @return
*/
@ApiOperation(value = "创建用户", notes = "根据User对象创建用户")
@ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
@RequestMapping(value = "", method = RequestMethod.POST)
public String postUser(@RequestBody User user) {
// 入库操作略
return "success";
}

/**
* 根据ID查询用户
*/
@ApiOperation(value = "获取用户详细信息", notes = "根据id来获取用户详细信息")
@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long")
@RequestMapping(value = "/{id}", method = RequestMethod.GET)
public User getUser(@PathVariable Long id) {
return new User();
}

}
  就稍微写两个接口,其他类似
   4:访问页面http://localhost:8080/swagger-ui.html  



点击相关的接口,查看出入参,可执行try it out进行测试