版权声明:本文为博主原创文章,转载请注明出处http://blog.csdn.net/saytime https://blog.csdn.net/saytime/article/details/74937664 </div>
<link rel="stylesheet" href="https://csdnimg.cn/release/phoenix/template/css/ck_htmledit_views-f57960eb32.css">
<link rel="stylesheet" href="https://csdnimg.cn/release/phoenix/template/css/ck_htmledit_views-f57960eb32.css">
<div class="htmledit_views" id="content_views">
相信各位在公司写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
-
*/
-
@Configuration
-
public
class Swagger2 {
-
-
@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
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
-
*/
-
@RestController
-
public
class UserController {
-
-
// 创建线程安全的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;
-
-
//
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:多个请求参数