SpringBoot(七):SpringBoot整合Swagger2
来源:互联网 发布:eclipse怎么编写java 编辑:程序博客网 时间:2024/05/16 15:44
相信各位在公司写API文档数量应该不少,当然如果你还处在自己一个人开发前后台的年代,当我没说,如今为了前后台更好的对接,还是为了以后交接方便,都有要求写API文档。
手写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 */@Configurationpublic class Swagger2 {@Beanpublic 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@EnableSwagger2public class SpringbootSwagger2Application {public static void 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 */@RestControllerpublic class UserController {// 创建线程安全的Mapstatic 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;// Getter Setter}
实体User.class
package cn.saytime.bean;import java.util.Date;/** * @author zh * @ClassName cn.saytime.bean.User * @Description */public class User {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:多个请求参数
阅读全文
1 0
- SpringBoot(七):SpringBoot整合Swagger2
- SpringBoot整合Swagger2
- 个人推荐:SpringBoot整合Swagger2
- SpringBoot -- Swagger2
- SpringBoot + Swagger2
- Swagger(一) SpringBoot整合Swagger2简单的例子
- Swagger(一) SpringBoot整合Swagger2简单的例子
- Springboot整合swagger2项目的部署问题
- springboot实战之整合restful工具swagger2
- 9.springboot整合swagger2生成rest-api
- springboot(六)配置swagger2
- Springboot集成swagger2
- springboot+swagger2说明
- springboot接入swagger2
- springboot+swagger2说明
- springboot项目集成Swagger2
- SpringBoot集成Swagger2
- springboot集成swagger2
- Android之CardView的使用
- 详解Response、Request二
- 将数组写入txt读出后数据出错
- poj 3461 kmp算法
- 代理模式
- SpringBoot(七):SpringBoot整合Swagger2
- 1057. 数零壹(20)
- 并发AQS同步器
- TCP/IP协议之IP协议
- POJ3159 最大差距(差分约束系统) (K)
- PAT b1031-b1035题解
- CentOS_6.5下安装tomcat-7.0.69
- 【C语言】操作符
- 并发基础_1_序