swagger是一个功能强大的api框架,它的集成非常简单,不仅提供了在线文档的查阅,而且还提供了在线文档的测试。另外swagger很容易构建restful风格的api,简单优雅帅气。
1、引入依赖
在pom.xml中加入Swagger2的依赖
<properties>
<swagger.version>2.7.0</swagger.version>
</properties>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>${swagger.version}</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>${swagger.version}</version>
</dependency>
2、创建Swagger2配置类
我是在Application.java同级下创建了一个conf文件夹,将所有配置类放在里面,方便管理。
@Configuration
@EnableSwagger2
public class Swagger2 {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
//.host("ps.bonc.com.cn")
.useDefaultResponseMessages(false)
.select()
.apis(RequestHandlerSelectors.basePackage("com.bonc.controller"))
//.apis(RequestHandlerSelectors.any())//扫描所有
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("springboot利用swagger构建api文档")
.description("简单优雅的restfun风格")
.termsOfServiceUrl("http://blog.csdn.net/forezp")
.contact("程序猿")
.version("1.0")
.build();
}
}
通过@Configuration注解,表明它是一个配置类,让Spring来加载该类配置。再通过@EnableSwagger2注解来启用Swagger2。
通过createRestApi函数创建Docket的Bean之后,apiInfo()用来创建该Api的基本信息(这些基本信息会展现在文档页面中)。select()函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现,本例采用指定扫描的包路径来定义,Swagger会扫描该包下所有Controller定义的API,并产生文档内容(除了被@ApiIgnore指定的请求)。
3、举例说明
@RestController
@RequestMapping(value = "/area")//通过这里配置使下面的映射都在/users下,可去除
public class AreaController {
@Autowired
private IAreaService areaService;
private static Logger logger = Logger.getLogger(GoodsController.class);
@ApiOperation(value = "热卖商品排名", notes = "热卖商品排名")
@RequestMapping(value = "goodsRank", method = RequestMethod.POST)
private ResultEntity goodsRank(@RequestBody Param param) {
ResultEntity result = new ResultEntity();
String msg = "查询成功";
boolean success = true;
try {
List<Map<String, Object>> re = areaService.goodsRank(param);
result.setData(re);
} catch (Exception e) {
logger.error("goodsError", e);
msg = "服务器错误!";
success = false;
}
result.setMsg(msg);
result.setSuccess(success);
return result;
}
@ApiOperation(value="创建图书", notes="创建图书")
@ApiImplicitParam(name = "book", value = "图书详细实体", required = true, dataType = "Book")
@RequestMapping(value="", method=RequestMethod.POST)
public String postBook(@RequestBody Book book) {
books.put(book.getId(), book);
return "success";
}
@ApiOperation(value="获图书细信息", notes="根据url的id来获取详细信息")
@ApiImplicitParam(name = "id", value = "ID", required = true, dataType = "Long",paramType = "path")
@RequestMapping(value="/{id}", method=RequestMethod.GET)
public Book getBook(@PathVariable Long id) {
return books.get(id);
}
@ApiOperation(value="更新信息", notes="根据url的id来指定更新图书信息")
@ApiImplicitParams({
@ApiImplicitParam(name = "id", value = "图书ID", required = true, dataType = "Long",paramType = "path"),
@ApiImplicitParam(name = "book", value = "图书实体book", required = true, dataType = "Book")
})
@RequestMapping(value="/{id}", method= RequestMethod.PUT)
public String putUser(@PathVariable Long id, @RequestBody Book book) {
Book book1 = books.get(id);
book1.setName(book.getName());
book1.setPrice(book.getPrice());
books.put(id, book1);
return "success";
}
@ApiOperation(value="删除用户", notes="根据url的id来指定删除对象")
@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long")
@RequestMapping(value="/{id}", method=RequestMethod.DELETE)
public String deleteUser(@PathVariable Long id) {
users.remove(id);
return "success";
}
@ApiIgnore//使用该注解忽略这个API
@RequestMapping(value = "/hi", method = RequestMethod.GET)
public String jsonTest() {
return " hi you!";
}
}
通过相关注解,就可以让swagger2生成相应的文档。如果你不需要某接口生成文档,只需要在加@ApiIgnore注解即可。需要说明的是,如果请求参数在url上,@ApiImplicitParam 上加paramType = “path” 。
启动工程,访问:http://localhost:8080/swagger-ui.html ,就看到swagger-ui: