概述
关于Open API
Open API(开放API)是服务型网站常用的一种应用，网站的服务商将自己的网站服务封装成一系列API(应用编程接口)对外开放，供第三方开发者使用。
Open API类型上分为标准REST和类REST（RPC形态）。
REST类型具有如下优点：
服务地址就是资源定位地址
服务操作就是Http请求中的方法类型(GET、POST、DELETE、PUT)
资源易于管理，系统扩展容易，权限控制部分依托于现有协议
类REST类型具有如下优点:
对原有改造较小
易于对逻辑进行抽象
Open API服务类型
数据型
将自身数据资源开放，让应用开发者根据已有数据资源进行二次开发。
应用型
与数据型应用紧密结合，数据输入可以是外部的数据资源，也可以是自身已有数据资源。
服务型
多用于云计算和资源存储
Open API交互数据格式
对于数据型和应用型服务来说，主要提供的数据响应格式为XML和JSON。
关于 Swagger
在前后端分离的开发模式下，为了减小接口定义沟通成本，需要使用Swagger。Swagger是一个规范和框架，用于生成、描述、调用和可视化RestFul风格的Web资源服务。
SwaggerUI使用详解
Swagger常用注解
| 注解名称 | 注解说明 | 作用域 |
| @Api | 用在控制器上，对控制器进行说明 | 控制器 |
| @ApiOperation | 用在控制器相关方法上，对请求方法、作用进行描述 | 控制器方法 |
| @ApiImplicitParams | 用在请求方法上，对一组请求参数进行说明，配合@ApiImplicitParam使用 | 控制器方法 |
| @ApiImplicitParam | 用在@ApiImplicitParams注解中，对请求参数进行说明 | @ApiImplicitParams中表示一组参数，单独使用表示一个参数 |
| @ApiResponses | 用在控制器方法上，表示一组请求响应,配合@ApiResponse使用 | 控制器方法 |
| @ApiResponse | 用在@ApiResponses中，表示请求相应信息 | @ApiResponses中 |
| @ApiModel | 用在数据载体上，描述响应数据信息 | 实体类 |
| @ApiModelProperty | 用在数据载体的属性字段上，描述响应数据属性信息 | 实体类属性字段 |
package com.springboot.demo.swagger2.controller;@Api(tags = "员工信息操作")@Controller@RequestMapping("/employee")public class EmployeeController {@ApiOperation(value = "查询所有员工集合信息",notes = "查询所有员工列表")@RequestMapping(value = "/findAll",method = RequestMethod.GET)@ResponseBodypublic String findAllEmployee(){}@ApiOperation(value = "根据员工标识获取员工详情信息",notes = "获取员工详情")@ApiImplicitParam(name = "employeeId",value = "员工标识",required = true,paramType ="path")@RequestMapping(value = "/getEmployee/{employeeId}",method = RequestMethod.GET)public String getEmployeeByEmployeeId(@PathVariable String employeeId){}@ApiOperation(value = "员工登录信息校验",notes = "员工登录校验")@ApiImplicitParams({@ApiImplicitParam(name = "userName", value = "用户名", required = true, paramType = "query"),@ApiImplicitParam(name = "userPwd", value = "登录密码", required = true, paramType = "query")})@RequestMapping(value = "/checklogin",method = RequestMethod.GET)public String checkLogin(@RequestParam String userName,@RequestParam String userPwd){}@ApiOperation(value = "保存员工信息",notes = "保存员工信息")@ApiImplicitParam(name = "employee",value = "被保存员工信息",required = true,paramType = "query")@ApiResponses({@ApiResponse(code = 200, message = "员工保存成功"),@ApiResponse(code = 500, message = "服务器错误"),@ApiResponse(code = 404, message = "请求路径错误")})@RequestMapping(value = "/saveEmployee",method = RequestMethod.POST)public String saveEmployee(@RequestParam Employee employee){}@ApiOperation(value="删除员工信息",notes = "删除员工信息")@ApiImplicitParam(value = "员工标识",name = "employeeId",required = true,paramType = "query")@ApiResponses({@ApiResponse(code = 200, message = "员工删除成功"),@ApiResponse(code = 500, message = "服务器错误"),@ApiResponse(code = 404, message = "请求路径错误")})@RequestMapping(value = "/removeEmployee",method = RequestMethod.DELETE)public String deleteEmployee(@RequestParam String employeeId){}}
@Api
用在控制器上，对控制器进行说明。tags用于描述控制器信息。
@ApiOperation
用在请求方法上，对方法的作用、用途信息进行说明。value:用于描述方法作用、用途；notes:方法备注说明
@ApiImplicitParam
用在请求方法上，对请求参数进行说明。name：参数名称;value:参数描述信息;required:是否必填;paramType:参数获取方式（header:@RequestHeader;query:@RequestParam;path:@PathVariable）。可以单独使用，也可以和 @ApiImplicitParams注解结合使用。
@ApiImplicitParams
用在请求方法上，对一组请求参数进行说明。
@ApiResponses
用在请求方法上，对一组请求响应信息进行说明。
@ApiResponse
用在@ApiResponses注解中，对状态码对应响应信息进行描述。code:响应码信息(与http响应码一致)，message:响应码对应描述。
@ApiModel(value = "员工信息",description = "员工信息")public class Employee implements Serializable{@ApiModelProperty(value = "员工标识",hidden = true,example = "xxxxxx")private String employeeId;@ApiModelProperty(value="登录用户名",required = true,dataType = "String")private String loginName;@ApiModelProperty(value="登录密码",required = true,dataType = "String")private String loginPwd;}复制
@ApiModel
该注解通常标注在数据载体上，表示响应数据载体相关信息。value:数据载体说明信息；description:数据载体描述信息。
@ApiModelProperty
该注解通常标注在数据载体属性字段上，表示响应数据载体属性字段相关信息。value:字段说明信息；required:是否必填；dataType:字段数据类型。
使用Swagger-Bootstrap-ui
引入依赖
<!--引入Swagger2依赖--><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.9.2</version></dependency><!--引入swagger-bootstrap-ui依赖--><dependency><groupId>com.github.xiaoymin</groupId><artifactId>swagger-bootstrap-ui</artifactId><version>1.9.0</version></dependency>复制
创建Swagger配置类
@Configuration@EnableSwagger2@ComponentScan("com.springboot.demo.swagger2.controller")@EnableSwaggerBootstrapUIpublic class Swagger2Config {@Beanpublic Docket createRestApi(){return new Docket(DocumentationType.SWAGGER_2).apiInfo(createApiInfo()).select().apis(RequestHandlerSelectors.basePackage("")).paths(PathSelectors.any()).build();}private ApiInfo createApiInfo(){return new ApiInfoBuilder().title("")//标题.description("")//描述.termsOfServiceUrl("")//服务网站.contact(new Contact("","",""))//三个参数依次是名称、网站地址、邮箱.version("1.0").build();}}
访问http://{host}:{port}/doc.html
