手写Api文档的几个痛点:
- 文档需要更新的时候,需要再次发送一份给前端,也就是文档更新交流不及时。
- 接口返回结果不明确
- 不能直接在线测试接口,通常需要使用工具,比如postman
- 接口文档太多,不好管理
Swagger也就是为了解决这个问题,当然也不能说Swagger就一定是完美的,当然也有缺点,最明显的就是代码移入性比较强。
其他的不多说,想要了解Swagger的,可以去Swagger官网,可以直接使用Swagger editor编写接口文档,当然我们这里讲解的是SpringBoot整合Swagger2,直接生成接口文档的方式。
一、依赖
-
<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>
二、Swagger配置类
其实这个配置类,只要了解具体能配置哪些东西就好了,毕竟这个东西配置一次之后就不用再动了。 特别要注意的是里面配置了api文件也就是controller包的路径,不然生成的文档扫描不到接口。
-
package cn.saytime;
-
-
import org.springframework.context.annotation.Bean;
-
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;
-
-
/**
-
* @author zh
-
* @ClassName cn.saytime.Swgger2
-
* @Description
-
* @date 2017-07-10 22:12:31
-
*/
-
@Configuration
-
public classSwagger2{
-
-
@Bean
-
public Docket createRestApi() {
-
return new Docket(DocumentationType.SWAGGER_2)
-
.apiInfo(apiInfo())
-
.select()
-
.apis(RequestHandlerSelectors.basePackage("cn.saytime.web"))
-
.paths(PathSelectors.any())
-
.build();
-
}
-
-
private ApiInfo apiInfo() {
-
return new ApiInfoBuilder()
-
.title("springboot利用swagger构建api文档")
-
.description("简单优雅的restfun风格,http://blog.csdn.net/saytime")
-
.termsOfServiceUrl("http://blog.csdn.net/saytime")
-
.version("1.0")
-
.build();
-
}
-
}
用@Configuration注解该类,等价于XML中配置beans;用@Bean标注方法等价于XML中配置bean。
Application.class 加上注解@EnableSwagger2 表示开启Swagger
-
package cn.saytime;
-
-
import org.springframework.boot.SpringApplication;
-
import org.springframework.boot.autoconfigure.SpringBootApplication;
-
import springfox.documentation.swagger2.annotations.EnableSwagger2;
-
-
@SpringBootApplication
-
@EnableSwagger2
-
public classSpringbootSwagger2Application{
-
-
publicstaticvoid main(String[] args) {
-
SpringApplication.run(SpringbootSwagger2Application.class, args);
-
}
-
}
三、Restful 接口
-
package cn.saytime.web;
-
-
import cn.saytime.bean.JsonResult;
-
import cn.saytime.bean.User;
-
import io.swagger.annotations.Api;
-
import io.swagger.annotations.ApiImplicitParam;
-
import io.swagger.annotations.ApiImplicitParams;
-
import io.swagger.annotations.ApiOperation;
-
import org.springframework.http.ResponseEntity;
-
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 springfox.documentation.annotations.ApiIgnore;
-
-
import java.util.ArrayList;
-
import java.util.Collections;
-
import java.util.HashMap;
-
import java.util.List;
-
import java.util.Map;
-
-
/**
-
* @author zh
-
* @ClassName cn.saytime.web.UserController
-
* @Description
-
*/
-
@RestController
-
public classUserController{
-
-
// 创建线程安全的Map
-
static Map<Integer, User> users = Collections.synchronizedMap(new HashMap<Integer, User>());
-
-
/**
-
* 根据ID查询用户
-
* @param id
-
* @return
-
*/
-
@ApiOperation(value="获取用户详细信息", notes="根据url的id来获取用户详细信息")
-
@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Integer", paramType = "path")
-
@RequestMapping(value = "user/{id}", method = RequestMethod.GET)
-
public ResponseEntity<JsonResult> getUserById (@PathVariable(value = "id") Integer id){
-
JsonResult r = new JsonResult();
-
try {
-
User user = users.get(id);
-
r.setResult(user);
-
r.setStatus("ok");
-
} catch (Exception e) {
-
r.setResult(e.getClass().getName() + ":" + e.getMessage());
-
r.setStatus("error");
-
e.printStackTrace();
-
}
-
return ResponseEntity.ok(r);
-
}
-
-
/**
-
* 查询用户列表
-
* @return
-
*/
-
@ApiOperation(value="获取用户列表", notes="获取用户列表")
-
@RequestMapping(value = "users", method = RequestMethod.GET)
-
public ResponseEntity<JsonResult> getUserList (){
-
JsonResult r = new JsonResult();
-
try {
-
List<User> userList = new ArrayList<User>(users.values());
-
r.setResult(userList);
-
r.setStatus("ok");
-
} catch (Exception e) {
-
r.setResult(e.getClass().getName() + ":" + e.getMessage());
-
r.setStatus("error");
-
e.printStackTrace();
-
}
-
return ResponseEntity.ok(r);
-
}
-
-
/**
-
* 添加用户
-
* @param user
-
* @return
-
*/
-
@ApiOperation(value="创建用户", notes="根据User对象创建用户")
-
@ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
-
@RequestMapping(value = "user", method = RequestMethod.POST)
-
public ResponseEntity<JsonResult> add (@RequestBody User user){
-
JsonResult r = new JsonResult();
-
try {
-
users.put(user.getId(), user);
-
r.setResult(user.getId());
-
r.setStatus("ok");
-
} catch (Exception e) {
-
r.setResult(e.getClass().getName() + ":" + e.getMessage());
-
r.setStatus("error");
-
-
e.printStackTrace();
-
}
-
return ResponseEntity.ok(r);
-
}
-
-
/**
-
* 根据id删除用户
-
* @param id
-
* @return
-
*/
-
@ApiOperation(value="删除用户", notes="根据url的id来指定删除用户")
-
@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long", paramType = "path")
-
@RequestMapping(value = "user/{id}", method = RequestMethod.DELETE)
-
public ResponseEntity<JsonResult> delete (@PathVariable(value = "id") Integer id){
-
JsonResult r = new JsonResult();
-
try {
-
users.remove(id);
-
r.setResult(id);
-
r.setStatus("ok");
-
} catch (Exception e) {
-
r.setResult(e.getClass().getName() + ":" + e.getMessage());
-
r.setStatus("error");
-
-
e.printStackTrace();
-
}
-
return ResponseEntity.ok(r);
-
}
-
-
/**
-
* 根据id修改用户信息
-
* @param user
-
* @return
-
*/
-
@ApiOperation(value="更新信息", notes="根据url的id来指定更新用户信息")
-
@ApiImplicitParams({
-
@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long",paramType = "path"),
-
@ApiImplicitParam(name = "user", value = "用户实体user", required = true, dataType = "User")
-
})
-
@RequestMapping(value = "user/{id}", method = RequestMethod.PUT)
-
public ResponseEntity<JsonResult> update (@PathVariable("id") Integer id, @RequestBody User user){
-
JsonResult r = new JsonResult();
-
try {
-
User u = users.get(id);
-
u.setUsername(user.getUsername());
-
u.setAge(user.getAge());
-
users.put(id, u);
-
r.setResult(u);
-
r.setStatus("ok");
-
} catch (Exception e) {
-
r.setResult(e.getClass().getName() + ":" + e.getMessage());
-
r.setStatus("error");
-
-
e.printStackTrace();
-
}
-
return ResponseEntity.ok(r);
-
}
-
-
@ApiIgnore//使用该注解忽略这个API
-
@RequestMapping(value = "/hi", method = RequestMethod.GET)
-
public String jsonTest() {
-
return " hi you!";
-
}
-
}
Json格式输出类 JsonResult.class
-
package cn.saytime.bean;
-
-
public class JsonResult{
-
-
private String status = null;
-
-
private Object result = null;
-
-
// GetterSetter
-
}
实体User.class
-
package cn.saytime.bean;
-
-
import java.util.Date;
-
-
/**
-
* @author zh
-
* @ClassName cn.saytime.bean.User
-
* @Description
-
*/
-
public classUser{
-
-
private int id;
-
private String username;
-
private int age;
-
private Date ctm;
-
-
// Getter Setter
-
}
项目结构:
四、Swagger2文档
启动SpringBoot项目,访问 http://localhost:8080/swagger-ui.html
具体里面的内容以及接口测试,应该一看就懂了。这里就不一一截图了。
五、Swagger注解
swagger通过注解表明该接口会生成文档,包括接口名、请求方法、参数、返回信息的等等。
- @Api:修饰整个类,描述Controller的作用
- @ApiOperation:描述一个类的一个方法,或者说一个接口
- @ApiParam:单个参数描述
- @ApiModel:用对象来接收参数
- @ApiProperty:用对象接收参数时,描述对象的一个字段
- @ApiResponse:HTTP响应其中1个描述
- @ApiResponses:HTTP响应整体描述
- @ApiIgnore:使用该注解忽略这个API
- @ApiError :发生错误返回的信息
- @ApiImplicitParam:一个请求参数
- @ApiImplicitParams:多个请求参数
相关推荐
springboot整合swagger2实例
springboot整合swagger2的demo swagger2 是一个规范和完整的框架,用于生成、描述、调用和可视化Restful风格的web服务,现在我们使用spring boot 整合它
SpringBoot整合Swagger2,详细文档,切实好用
springBoot整合Swagger项目例子,简单的代码,希望可以帮助到有需要的人
SpringBoot整合Swagger2并且可以向数据库写入数据,使用工具IDEA
springboot整合Swagger2实现API接口,代码一键可用。
在本篇文章里小编给大家整合了关于SpringBoot整合Swagger2的相关知识点内容,有兴趣的朋友们学习下。
springboot整合swagger2,高效制作漂亮整洁的接口文档必备
springboot整合swagger小栗子
springboot 整合swagger2.0支持API注释显示 springboot 整合swagger2.0支持API注释显示 springboot 整合swagger2.0支持API注释显示
springboot整合swagger-bootstrap-ui,过滤器放开并解决自定义错误信息返回冲突-DEMO
springboot整合swagger.zip
自己无聊时做的一套springboot整合swagger和mybatis-plus的案例,刚入门的小伙伴可以看一下,大家一起探讨探讨
主要介绍了SpringBoot整合Swagger2代码实例,文中通过示例代码介绍的非常详细,对大家的学习或者工作具有一定的参考学习价值,需要的朋友可以参考下
springboot整合swagger构建Api文档,对于整理在线文档这是一大利器,相对于ssm整合是真的简单方便,不管是不是新手,一看就能懂,对于与前端交互,那是相当的便捷。
springboot整合swagger
最简单的springboot整合swagger案例 ,下载直接可以运行,运行访问地址是http://127.0.0.1:7722/g11n/swagger-ui.html#!/test/test
springboot整合swagger