使用Spring Boot&Swagger快速构建REST API并生成优美的API文档
来源:互联网 发布:mac office 没有权限 编辑:程序博客网 时间:2024/06/05 21:15
使用Spring Boot&Swagger快速构建REST API并生成优美的API文档
通常我们要构建API 服务,自然少不了文档,但由于API与文档的分离使得我们每次对API进行的更改都需要去同步文档,稍有纰漏难免就会出现调用的异常,而编写、同步文档通常是比较繁琐无趣的事。现在得益于Spring Boot 与Swagger,我们不但可以极速的搭建REST、RESTful风格的API服务并且还可以生成优美、强大的在线或离线API文档。
引入Maven依赖
<parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>1.4.1.RELEASE</version> </parent> <dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <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> </dependencies>
创建Application主类
package example;//注意包结构@SpringBootApplicationpublic class Application { public static void main(String[] args) throws Exception { SpringApplication.run(Application.class, args); }}
创建Swagger配置类
package example.config;//注意包结构@Configuration@EnableSwagger2public class Swagger2Configuration { @Bean public Docket buildDocket() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(buildApiInf()) .select() .apis(RequestHandlerSelectors.basePackage("example.web.controller"))//要扫描的API(Controller)基础包 .paths(PathSelectors.any()) .build(); } private ApiInfo buildApiInf() { return new ApiInfoBuilder() .title("Spring Boot中使用Swagger2 UI构建API文档") .contact("土豆") .version("1.0") .build(); }}
创建RestController 构建一个简单计算服务API
package example.web.controller;//注意包结构@Api(value = "计算服务",description="简单的计算服务,提供加减乘除运算API")@RestController@RequestMapping("/compute")public class ComputeController { @ApiOperation("加法运算") @PostMapping("/add") public Double add(@RequestParam Double a, @RequestParam Double b) { return a + b; } @ApiOperation("减法运算") @PostMapping("/sub") public Double sub(@RequestParam Double a, @RequestParam Double b) { return a - b; } @ApiOperation("乘法运算") @PostMapping("/mul") public Double mul(@RequestParam Double a, @RequestParam Double b) { return a * b; } @ApiOperation("除法运算") @PostMapping("/div") public Double div(@ApiParam("被除数")@RequestParam Double a, @ApiParam("除数")@RequestParam Double b) { return a / b; }}
@Api
注解用来表述该服务的信息,如果不使用则显示类名称.@ApiOperation
注解用于表述接口信息@ApiParam
注解用于描述接口的参数
通过上面几步我们已经成功构建了一个具备加减乘除的计算服务API,并且已经拥有一份不错的在线文档了,现在我们来启动它,执行mvn spring-boot:run
,或直接运行Application.main()
。
启动成功后,访问http://localhost:8080/swagger-ui.html,便可以看到我们刚才构建的计算服务的API文档了。
Swagger UI不仅仅是文档,还提供了在线API调试的功能,我们可以调试下我们的除法运算API。
点击Try it out!后可以看到我们成功的调用了除法运算API并获得了正确的响应。
创建RESTful 风格的API及文档
下面我们以用户的增删改查服务为例
1.创建Model
package example.model;//注意包结构public class User { private Long id; private String username; private Integer age; //省略getter、setter方法}
2.创建RestController
package example.web.controller;//注意包结构@RestController@RequestMapping("/user")@Api(value = "用户服务",description = "提供RESTful风格API的用户的增删改查服务")public class UserController { //模拟DAO层 private final Map<Long, User> repository = new HashMap<Long, User>(); @PostMapping @ApiOperation("添加用户") public Boolean add(@RequestBody User user) { repository.put(user.getId(), user); return true; } @DeleteMapping("/{id}") @ApiOperation("通过ID删除用户") public Boolean delete(@PathVariable Long id) { repository.remove(id); return true; } @PutMapping @ApiOperation("更新用户") public Boolean update(@RequestBody User user) { repository.put(user.getId(), user); return true; } @GetMapping("/{id}") @ApiOperation("通过ID查询用户") public User findById(@PathVariable Long id) { return repository.get(id); }}
这里说点题外话,@GetMapping,@PostMapping,@PutMapping,@DeleteMapping
等注解是Spring MVC 4.3X
版本添加的新注解,它们是对@RequestMapping
注解的简化封装。
好了,我们重新启动下Application,再次访问http://localhost:8080/swagger-ui.html,用户服务的RESTful API文档也已生成。
我们来尝试调用添加用户API增加一位用户
成功后,我们调用查询API,来进行查询看时候可以返回正确的JSON数据。
为Model(JSON)添加注释
为了使API的调用者能够清晰的知道请求和响应的Model中各字段的具体含义,我们需要对其添加一些简单的注释,而Swagger也为我们提供了相应的注解比如@ApiModel、@ApiModelProperty
来帮助我们解释我们的Model,下面就是最简单的使用例子,详细用法及更多相关注解点我查看~
@ApiModel("User(用户模型)")public class User { @ApiModelProperty("ID") private Long id; @ApiModelProperty("用户名") private String username; @ApiModelProperty("年龄") private Integer age; //省略getter、setter方法}
这一切是不是很简单?从开发API到构建高逼格的API文档完全可以用极速来形容。当然,本文也只是展现了Spring Boot + Swagger的冰山一角,要了解更多细节那就快去翻阅官方文档吧~
本示例完整代码的GIT地址点击我~
Swagger-Core文档点击我~
SpringFox文档点击我~
Spring Boot 文档点击我~
还不错的Spring Boot系列教程点击我~
- 使用Spring Boot&Swagger快速构建REST API并生成优美的API文档
- SpringBoot + mybatis + Swagger快速构建REST API并生成优美的API文档
- SpringBoot&Swagger构建REST API并生成API文档
- 使用Swagger,Swagger-UI生成REST API接口文档
- swagger ui和spring boot集成生成api文档
- Spring boot结合swagger自动生成api文档
- 8.5 Spring Boot集成Swagger2构建自动化Rest API文档
- Spring Boot如何让Web API自动生成文档,并解决swagger-annotations的API注解description属性废弃的问题
- Spring boot构建RESTFul API+使用Swagger2构建API文档
- 基于Nginx+Spring Boot+Swagger的api文档实践
- Spring MVC中使用Swagger生成API文档和完整项目示例Demo,swagger-server-api
- Spring MVC中使用Swagger生成API文档和完整项目示例Demo,swagger-server-api
- Spring MVC中使用Swagger生成API文档和完整项目示例Demo,swagger-server-api
- Spring MVC中使用Swagger生成API文档和完整项目示例Demo,swagger-server-api
- Spring MVC中使用Swagger生成API文档和完整项目示例Demo,swagger-server-api
- Spring MVC中使用Swagger生成API文档和完整项目示例Demo,swagger-server-api
- Spring MVC中使用Swagger生成API文档和完整项目示例Demo,swagger-server-api
- Spring MVC中使用Swagger生成API文档
- mybatis-generator-tool工具的使用
- MVC的概念
- Java反射
- CentOS7上elasticsearch5.0启动失败
- Codevs 1959 拔河比赛
- 使用Spring Boot&Swagger快速构建REST API并生成优美的API文档
- 市场研究中的数据分析知识整理 (八)-关联法则
- 微信小程序输出html内容数据插件wxParse
- maven项目没有src/main/java和src/test/java
- param=(function(obj){})(param);的理解
- 7个改变世界的Java项目
- HDFS权限管理用户指南
- 用systrace分析卡顿问题
- linux 6.4 平台下 Oracle 12c 单实例 安装手册