【swagger】1.swagger提供开发者文档--简单集成到spring boot中【spring mvc】【spring boot】

swagger提供开发者文档

========================================================

作用:想使用swagger的同学,一定是想用它来做前后台分离,后台开发为前台提供API,以供前台的同学调用和调试。

那么swagger的作用就是上面这句话。

具体swagger包含了哪些,swagger官网展示的很齐全

【swagger】1.swagger提供开发者文档--简单集成到spring boot中【spring mvc】【spring boot】

本篇只表达swagger2+spring boot怎么用,也是给想用swagger但是无从下手的同学们带带路!!!!

========================================================

本篇需要准备的东西:

InterllJ Idea/JDK1.8/spring boot 项目一个

========================================================

在这开始之前,你要自己去搭建一个spring boot项目,至于使用maven管理架包或者gradle管理架包,看你自己。

参考地址:

http://www.cnblogs.com/sxdcgaq8080/p/7712874.html. maven+spring boot

http://www.cnblogs.com/sxdcgaq8080/p/8717914.html gradle+spring boot

1.添加依赖

gradle添加依赖

// https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui
compile group: 'io.springfox', name: 'springfox-swagger-ui', version: '2.8.0'
// https://mvnrepository.com/artifact/io.springfox/springfox-swagger2
compile group: 'io.springfox', name: 'springfox-swagger2', version: '2.8.0'

maven添加依赖

<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.8.0</version>
</dependency> <dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.8.0</version>
</dependency>

2.swagger配置类

其实这个配置类,只要了解具体能配置哪些东西就好了,毕竟这个东西配置一次之后就不用再动了。

【注意1】:特别要注意的是里面配置了api文件也就是controller包的路径,你要生成API接口文档的controller文件都是放在这个包路径下的,不然生成的文档扫描不到接口。

【注意2】:这个swagger配置类,是要放在你Application类同级,也就是Springboot项目的启动类的同级

package com.sxd.sweeping;

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;
import springfox.documentation.swagger2.annotations.EnableSwagger2; @Configuration
@EnableSwagger2
public class Swagger2 { @Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.sxd.sweeping.controller"))
.paths(PathSelectors.any())
.build();
} private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Spring Boot中使用Swagger2构建RESTful APIs")
.description("更多精彩博客请关注:http://www.cnblogs.com/sxdcgaq8080/")
.termsOfServiceUrl("http://www.cnblogs.com/sxdcgaq8080/")
.contact("Angel挤一挤")
.version("1.0")
.build();
}
}

3.然后 就是最简单的controller的swagger的表达了

【注意1】:@ApiImplicitParam 和 @ApiParam 方式均能指定参数规则。

【注意2】:使用@ApiImplicitParam的时候,需要指定paramType。

package com.sxd.sweeping.controller;

import com.sxd.sweeping.entity.User;
import com.sxd.sweeping.repository.UserRepository;
import com.sxd.sweeping.response.GenericResponse;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*; import java.sql.Date;
import java.util.UUID; @Api(value = "userController",description = "用户相关操作",tags = {"用户"})
@RestController
@RequestMapping("users")
public class UserController { @Autowired
private UserRepository userRepository; @ApiOperation(value = "获取用户详细信息", notes = "根据url的id来获取用户的详细信息")
@ApiImplicitParam(name = "id", value = "用户ID", required = true,dataType = "Long",paramType = "path")
// @RequestMapping(value = "/{id}",method = RequestMethod.GET)
@GetMapping(value = "/{id}")
public GenericResponse<User> get(@PathVariable Long id){
User user = userRepository.findUserById(id);
GenericResponse<User> genericResponse = new GenericResponse<>();
genericResponse.setItems(user);
genericResponse.setCode(200);
if(user != null){
genericResponse.setMessage("查询成功");
}else{
genericResponse.setMessage("暂无此人");
}
return genericResponse;
} @ApiOperation(value = "增加用户", notes = "根据user对象创建用户")
@ApiImplicitParam(name = "user", value = "用户详细信息User", required = true,dataType = "User")
// @RequestMapping(method = RequestMethod.POST)
@PostMapping()
public GenericResponse<User> add(@RequestBody User user){
String password = UUID.randomUUID().toString();
user.setPassword(password);
user = userRepository.save(user); GenericResponse<User> genericResponse = new GenericResponse<>();
genericResponse.setItems(user);
genericResponse.setCode(200);
if(user != null){
genericResponse.setMessage("新增成功");
}else{
genericResponse.setMessage("新增失败");
}
return genericResponse;
} @ApiOperation(value = "删除用户", notes = "根据url的id来删除用户")
@ApiImplicitParam(name = "id", value = "用户ID", required = true,dataType = "Long",paramType = "path")
// @RequestMapping(value = "/{id}",method = RequestMethod.DELETE)
@DeleteMapping(value = "/{id}")
@ResponseBody
public GenericResponse<User> delete(@PathVariable Long id){
userRepository.deleteById(id);
GenericResponse<User> genericResponse = new GenericResponse<>();
genericResponse.setCode(200);
genericResponse.setMessage("删除成功"); return genericResponse;
} @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 = "/{id}",method = RequestMethod.PUT)
@PutMapping(value = "/{id}")
public GenericResponse<User> update(@PathVariable Long id, @RequestBody User user){
User user1 = userRepository.findUserById(id);
user1.setGender(user.getGender());
user1.setMobile(user.getMobile());
user1.setRealname(user.getRealname());
user1.setUpdateAt(new Date(System.currentTimeMillis())); GenericResponse<User> genericResponse = new GenericResponse<>();
genericResponse.setCode(200);
genericResponse.setMessage("更新成功");
genericResponse.setItems(userRepository.saveAndFlush(user1)); return genericResponse;
} @ApiOperation(value = "更新用户局部信息", notes = "根据url的id来更新用户局部信息")
@ApiImplicitParams({
@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long", paramType = "path"),
@ApiImplicitParam(name = "realname", value = "用户名", required = true,dataType = "String"),
@ApiImplicitParam(name = "mobile", value = "联系方式", required = true,dataType = "String")
})
// @RequestMapping(value = "/{id}",method = RequestMethod.PATCH)
@PatchMapping(value = "/{id}")
public GenericResponse<User> patch(@PathVariable Long id, String realname, String mobile){
User user = userRepository.findUserById(id);
user.setRealname(realname);
user.setMobile(mobile); GenericResponse<User> genericResponse = new GenericResponse<>();
genericResponse.setCode(200);
genericResponse.setMessage("更新成功");
genericResponse.setItems(userRepository.saveAndFlush(user)); return genericResponse;
} }

4.项目启动后,就可以访问地址:

http://localhost:8080/swagger-ui.html#

访问你的api接口了。

展示API页面如下:

【swagger】1.swagger提供开发者文档--简单集成到spring boot中【spring mvc】【spring boot】

【swagger】1.swagger提供开发者文档--简单集成到spring boot中【spring mvc】【spring boot】

【swagger】1.swagger提供开发者文档--简单集成到spring boot中【spring mvc】【spring boot】

==============================================================================

常用注解详情

swagger通过注解表明该接口会生成文档,包括接口名、请求方法、参数、返回信息的等等。

@Api:作用在controller类上,修饰整个类,描述Controller的作用
@ApiOperation:作用在controller类的方法上,描述一个类的一个方法,或者说一个接口的功能
@ApiParam:单个参数描述
@ApiModel:用在返回对象类上,用对象来接收参数
@ApiModelProperty:用在参数对象的字段上
@ApiProperty:用对象接收参数时,描述对象的一个字段
@ApiResponse:用在@ApiResponses里面,HTTP响应其中1个描述
@ApiResponses:用在controller方法上,HTTP响应整体描述
@ApiIgnore:使用该注解忽略这个API
@ApiError :发生错误返回的信息
@ApiImplicitParam:用在@ApiImplicitParams中,一个请求参数
@ApiImplicitParams:用在controller方法上,多个请求参数

各个注解中属性值的解析:

@ApiImplicitParam:用在 @ApiImplicitParams 注解中,指定一个请求参数的各个方面

paramType:参数放在哪个地方 
· header --> 请求参数的获取:@RequestHeader
· query -->请求参数的获取:@RequestParam
· path(用于restful接口)--> 请求参数的获取:@PathVariable
· body(不常用)
· form(不常用)
name:参数名
dataType:参数类型
required:参数是否必须传
value:参数的意思
defaultValue:参数的默认值
@Api:作用在controller类上,修饰整个类,描述Controller的作用

属性名称    备注
value url的路径值
tags 如果设置这个值、value的值会被覆盖
description 对api资源的描述
basePath 基本路径可以不配置
position 如果配置多个Api 想改变显示的顺序位置
produces For example, "application/json, application/xml"
consumes For example, "application/json, application/xml"
protocols Possible values: http, https, ws, wss.
authorizations 高级特性认证时配置
hidden 配置为true 将在文档中隐藏
@ApiOperation:作用在controller类的方法上,描述一个类的一个方法,或者说一个接口的功能

属性名称    备注
value url的路径值
tags 如果设置这个值、value的值会被覆盖
description 对api资源的描述
basePath 基本路径可以不配置
position 如果配置多个Api 想改变显示的顺序位置
produces For example, "application/json, application/xml"
consumes For example, "application/json, application/xml"
protocols Possible values: http, https, ws, wss.
authorizations 高级特性认证时配置
hidden 配置为true 将在文档中隐藏
response 返回的对象
responseContainer 这些对象是有效的 "List", "Set" or "Map".,其他无效
httpMethod "GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH"
code http的状态码 默认
extensions 扩展属性
@ApiParam:单个参数描述

示例:
public UniVerResponse<HuaYangArea> huayang(@ApiParam(value = "create a entity HuaYangArea") @RequestBody HuaYangArea huaYangArea) 属性名称 备注
name 属性名称
value 属性值
defaultValue 默认属性值
allowableValues 可以不配置
required 是否属性必填
access 不过多描述
allowMultiple 默认为false
hidden 隐藏该属性
example 举例子
@ApiResponse:用在@ApiResponses里面,HTTP响应其中1个描述

示例:
@ApiOperation(value = "保存HUAYANG信息",notes = "传入HUAYANG实体,保存HUAYANG信息")
@PostMapping()
@ApiResponses({
@ApiResponse(code = ,message = "success"),
@ApiResponse(code = ,message = "参数错误"),
@ApiResponse(code = ,message = "业务错误"),
@ApiResponse(code = ,message = "系统异常")})
public UniVerResponse<HuaYangArea> huayang(@ApiParam(value = "create a entity HuaYangArea") @RequestBody HuaYangArea huaYangArea){ 属性名称 备注
code http的状态码
message 描述
response 默认响应类 Void
reference 参考ApiOperation中配置
responseHeaders 参考 ResponseHeader 属性配置说明
responseContainer 参考ApiOperation中配置

==========================================================================

Get等价:

@RequestMapping(value = "/{id}",method = RequestMethod.GET)
等价于:@GetMapping(value = "/{id}")

Post等价:【创建资源】

@RequestMapping(method = RequestMethod.POST)
等价于:@PostMapping()

Delete等价:

@RequestMapping(value = "/{id}",method = RequestMethod.DELETE)
等价于:@DeleteMapping(value = "/{id}")

Put等价:【更新已存在的资源,完全替换,所以接收到的是id和完整的对象,在处理上如果对象中有未给值的字段,则更新数据库中字段值替换为空】

@RequestMapping(value = "/{id}",method = RequestMethod.PUT)
等价于:@PutMapping(value = "/{id}")

Patch等价:【更新已经存在资源的部分字段,局部更新,仅提供id和要更新的字段,在处理上仅更新要更新的字段,其他字段不变】

@RequestMapping(value = "/{id}",method = RequestMethod.PATCH)
等价于:@PatchMapping(value = "/{id}")

===========================================================================

【注意】:

因为返回的都是统一处理响应格式,所以每个API接口上都要加上@ResponseBody注解。

所以,可以选择在Controller上加上@RestController=@Controller+@ResponseBody

===========================================================================

下一篇地址:

http://www.cnblogs.com/sxdcgaq8080/p/8797318.html

上一篇:crontab 命令


下一篇:『重构--改善既有代码的设计』读书笔记----Introduce Local Extension