SpringBoot非官方教程 | 第十一篇:springboot集成swagger2,构建优雅的Restful API
转载请标明出处:
原文首发于:https://www.fangzhipeng.com/springboot/2017/07/11/springboot-swagger2/
本文出自方志朋的博客
swagger,中文“拽”的意思。它是一个功能强大的api框架,它的集成非常简单,不仅提供了在线文档的查阅,而且还提供了在线文档的测试。另外swagger很容易构建restful风格的api,简单优雅帅气,正如它的名字。
一、引入依赖
<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>
二、写配置类
@Configuration
@EnableSwagger2
public class Swagger2 {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.forezp.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("springboot利用swagger构建api文档")
.description("简单优雅的restfun风格,http://blog.csdn.net/forezp")
.termsOfServiceUrl("http://blog.csdn.net/forezp")
.version("1.0")
.build();
}
}
通过@Configuration注解,表明它是一个配置类,@EnableSwagger2开启swagger2。apiINfo()配置一些基本的信息。apis()指定扫描的包会生成文档。
三、写生产文档的注解
swagger通过注解表明该接口会生成文档,包括接口名、请求方法、参数、返回信息的等等。
- @Api:修饰整个类,描述Controller的作用
- @ApiOperation:描述一个类的一个方法,或者说一个接口
- @ApiParam:单个参数描述
- @ApiModel:用对象来接收参数
- @ApiProperty:用对象接收参数时,描述对象的一个字段
- @ApiResponse:HTTP响应其中1个描述
- @ApiResponses:HTTP响应整体描述
- @ApiIgnore:使用该注解忽略这个API
- @ApiError :发生错误返回的信息
- @ApiParamImplicitL:一个请求参数
- @ApiParamsImplicit 多个请求参数
现在通过一个栗子来说明:
package com.forezp.controller;
import com.forezp.entity.Book;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.ui.ModelMap;
import org.springframework.web.bind.annotation.*;
import springfox.documentation.annotations.ApiIgnore;
import java.util.*;
/**
* 用户创建某本图书 POST /books/
* 用户修改对某本图书 PUT /books/:id/
* 用户删除对某本图书 DELETE /books/:id/
* 用户获取所有的图书 GET /books
* 用户获取某一图书 GET /Books/:id
* Created by fangzhipeng on 2017/4/17.
* 官方文档:http://swagger.io/docs/specification/api-host-and-base-path/
*/
@RestController
@RequestMapping(value = "/books")
public class BookContrller {
Map<Long, Book> books = Collections.synchronizedMap(new HashMap<Long, Book>());
@ApiOperation(value="获取图书列表", notes="获取图书列表")
@RequestMapping(value={""}, method= RequestMethod.GET)
public List<Book> getBook() {
List<Book> book = new ArrayList<>(books.values());
return book;
}
@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",paramType = "path")
@RequestMapping(value="/{id}", method=RequestMethod.DELETE)
public String deleteUser(@PathVariable Long id) {
books.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:
整个集成过程非常简单,但是我看了相关的资料,swagger没有做安全方面的防护,可能需要我们自己做相关的工作。
四、参考资料
Spring Boot中使用Swagger2构建强大的RESTful API文档
扫码关注公众号有惊喜
(转载本站文章请注明作者和出处 方志朋的博客)
SpringBoot非官方教程 | 第十一篇:springboot集成swagger2,构建优雅的Restful API的更多相关文章
- (转) SpringBoot非官方教程 | 第十一篇:springboot集成swagger2,构建优雅的Restful API
swagger,中文“拽”的意思.它是一个功能强大的api框架,它的集成非常简单,不仅提供了在线文档的查阅,而且还提供了在线文档的测试.另外swagger很容易构建restful风格的api,简单优雅 ...
- Spring Boot2 系列教程 (四) | 集成 Swagger2 构建强大的 RESTful API 文档
前言 快过年了,不知道你们啥时候放年假,忙不忙.反正我是挺闲的,所以有时间写 blog.今天给你们带来 SpringBoot 集成 Swagger2 的教程. 什么是 Swagger2 Swagger ...
- 集成 Swagger2 构建强大的 RESTful API 文档
微信公众号:一个优秀的废人如有问题或建议,请后台留言,我会尽力解决你的问题. 前言 快过年了,不知道你们啥时候放年假,忙不忙.反正我是挺闲的,所以有时间写 blog.今天给你们带来 SpringBoo ...
- SpringBoot非官方教程 | 第二十一篇: springboot集成JMS
转载请标明出处: http://blog.csdn.net/forezp/article/details/71024024 本文出自方志朋的博客 springboot对JMS提供了很好的支持,对其做了 ...
- Spring Boot教程(二十三)使用Swagger2构建强大的RESTful API文档(2)
添加文档内容 在完成了上述配置后,其实已经可以生产文档内容,但是这样的文档主要针对请求本身,而描述主要来源于函数等命名产生,对用户并不友好,我们通常需要自己增加一些说明来丰富文档内容.如下所示,我们通 ...
- (转)第十一篇:springboot集成swagger2,构建优雅的Restful API
声明:本部分内容均转自于方志明博友的博客,因为本人很喜欢他的博客,所以一直在学习,转载仅是记录和分享,若也有喜欢的人的话,可以去他的博客首页看:http://blog.csdn.net/forezp/ ...
- springboot集成swagger2,构建优雅的Restful API
swagger,中文“拽”的意思.它是一个功能强大的api框架,它的集成非常简单,不仅提供了在线文档的查阅,而且还提供了在线文档的测试.另外swagger很容易构建restful风格的api,简单优雅 ...
- (转)SpringBoot非官方教程 | 第七篇:springboot开启声明式事务
springboot开启事务很简单,只需要一个注解@Transactional 就可以了.因为在springboot中已经默认对jpa.jdbc.mybatis开启了事事务,引入它们依赖的时候,事物就 ...
- SpringBoot非官方教程 | 第二十三篇: 异步方法
转载请标明出处: 原文首发于https://www.fangzhipeng.com/springboot/2017/07/11/springboot-ansy/ 本文出自方志朋的博客 这篇文章主要介绍 ...
随机推荐
- SpringSecurity 3.2入门(3)单用户登录
1.增加web.xml文件配置如下 <!-- 获取Spring Security session的生命周期,这个监听器会在 session 创建和销毁的时候通知 Spring Security ...
- 【JavaWeb】JSP九大内置对象
内置对象特点: 1. 由JSP规范提供,不用编写者实例化. 2. 通过Web容器实现和管理 3. 所有JSP页面均可使用 4. ...
- MySQL出现时区错误的解决方法
目录 环境 问题 分析 解决方法 环境 windows10 MySQL 8.0.13 IDEA 问题 The server time zone value 'Öйú±ê׼ʱ¼ä' is unre ...
- Android4.4 在Framework新增内部资源编译不过的问题
如果在Frameworks新增内部资源,并在Java代码中使用类似形式来引用资源:com.android.internal.R.layout.xxx,需要在frameworks/base/core/r ...
- mysql二:库操作
一.系统数据库 information_schema: 虚拟库,不占用磁盘空间,存储的是数据库启动后的一些参数,如用户表信息.列信息.权限信息.字符信息等 performance_schema: My ...
- Python爬虫《http和https协议》
一.HTTP协议 1.官方概念: HTTP协议是Hyper Text Transfer Protocol(超文本传输协议)的缩写,是用于从万维网(WWW:World Wide Web )服务器传输超文 ...
- 概述File i/o
1.File对象既可表示文件,也可表示目录(文件夹). 2. 创建一个File对象 File file = new File (String pathName[文件路径名]); 3.在Windows操 ...
- Drupal Module Hooks
Drupal is a Content Management System. Drupal is also deeply, deeply weird. While systems like Magen ...
- ref关键字的用法
ref 关键字通过引用(而非值)传递参数. 通过引用传递的效果是,对所调用方法中的参数进行的任何更改都反映在调用方法中. 例如,如果调用方传递本地变量表达式或数组元素访问表达式,所调用方法会将对象替换 ...
- Oracle VM virtualBox -Centos6.4 安装后没有网解决方法
1.先修改Oracle VM virtualBox 的网络配置 2.然后启动centos输入: dhclient eth0 3.然后如果没报错的话 输入: ifconfig 就可以查看到ip地址 ...