Swagger集成Springboot
Swagger集成Springboot
- 1.Swagger介绍
- 1.1.什么是Swagger
- 1.2.优势
- 2.Swagger使用
- 2.1.在pom.xml文件中添加第三方swagger依赖
- 2.1.2项目完整pom
- 2.2.yml配置
- 2.3.在Spring Boot项目的启动类上添加@EnableSwagger2，启动Swagger
- 2.4.添加配置类
- 2.5.User实体类
- 2.6.Mapper类(使用的通用mapper)
- 2.7.Service类
- 2.8.Service实现类
- 2.9.Controller类
- 3.访问
1.Swagger介绍
1.1.什么是Swagger
Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。
Swagger 的目标是对 REST API 定义一个标准且和语言无关的接口，可以让人和计算机拥有无须访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过 Swagger 进行正确定义，用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似，Swagger 消除了调用服务时可能会有的猜测。
1.2.优势
支持 API 自动生成同步的在线文档：使用 Swagger 后可以直接通过代码生成文档，不再需要自己手动编写接口文档了，对程序员来说非常方便，可以节约写文档的时间去学习新技术。
提供 Web 页面在线测试 API：光有文档还不够，Swagger 生成的文档还支持在线测试。参数和格式都定好了，直接在界面上输入参数对应的值即可在线测试接口。
2.Swagger使用
2.1.在pom.xml文件中添加第三方swagger依赖
<!--swagger jar start-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
<!--swagger jar end-->
2.1.2项目完整pom
<properties>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
<java.version>1.8</java.version>
<mybatis.starter.version>1.3.2</mybatis.starter.version>
<mapper.starter.version>2.0.2</mapper.starter.version>
<mysql.version>5.1.32</mysql.version>
<durid.starter.version>1.1.10</durid.starter.version>
</properties>
<dependencies>
<!-- SpringBoot整合SpringMVC的启动器 -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<!-- SpringBoot整合jdbc和事务的启动器 -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-jdbc</artifactId>
</dependency>
<!-- mybatis启动器 -->
<dependency>
<groupId>org.mybatis.spring.boot</groupId>
<artifactId>mybatis-spring-boot-starter</artifactId>
<version>${mybatis.starter.version}</version>
</dependency>
<!-- 通用Mapper启动器 -->
<dependency>
<groupId>tk.mybatis</groupId>
<artifactId>mapper-spring-boot-starter</artifactId>
<version>${mapper.starter.version}</version>
</dependency>
<!-- mysql驱动 -->
<dependency>
<groupId>mysql</groupId>
<artifactId>mysql-connector-java</artifactId>
<version>${mysql.version}</version>
</dependency>
<!-- Druid连接池 -->
<dependency>
<groupId>com.alibaba</groupId>
<artifactId>druid-spring-boot-starter</artifactId>
<version>${durid.starter.version}</version>
</dependency>
<!--swagger jar start-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
<!--swagger jar end-->
</dependencies>
2.2.yml配置
#Tomcat
server:
port: 9090
#DB configuration
spring:
application:
name: web-service
datasource:
url: jdbc:mysql://localhost:3306/work?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai
username: root
password: root
driver-class-name: com.mysql.jdbc.Driver
2.3.在Spring Boot项目的启动类上添加@EnableSwagger2，启动Swagger
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.netflix.eureka.EnableEurekaClient;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@SpringBootApplication
@EnableSwagger2
public class OneweekApplication {
public static void main(String[] args) {
SpringApplication.run(OneweekApplication.class, args);
}
}
2.4.添加配置类
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 Swagger2Config {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2).
apiInfo(apiInfo()).
select().
//自己的controller路径
apis(RequestHandlerSelectors.basePackage("com.capgemini.controller")).
paths(PathSelectors.any()).
build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder().
title("springboot利用swagger构建api文档").
description("用户的CRUD").
version("1.0").
build();
}
}
2.5.User实体类
package com.capgemini.domain;
import com.fasterxml.jackson.annotation.JsonFormat;
import org.springframework.format.annotation.DateTimeFormat;
import java.util.Date;
import javax.persistence.*;
@Table(name = "`user`")
public class User {
@Id
@Column(name = "id")
@GeneratedValue(generator = "JDBC")
private Integer id;
@Column(name = "username")
private String username;
@Column(name = "age")
private Integer age;
@Column(name = "sex")
private String sex;
@Column(name = "birthday")
@DateTimeFormat(pattern = "yyyy-MM-dd")
@JsonFormat(pattern = "yyyy-MM-dd", timezone = "GMT+8")
private Date birthday;
@Column(name = "phone")
private String phone;
@Transient
private String sencode;
@Transient
private String code;
public String getSencode() {
return sencode;
}
public void setSencode(String sencode) {
this.sencode = sencode;
}
public String getCode() {
return code;
}
public void setCode(String code) {
this.code = code;
}
/**
* @return id
*/
public Integer getId() {
return id;
}
/**
* @param id
*/
public void setId(Integer id) {
this.id = id;
}
public String getPhone() {
return phone;
}
public void setPhone(String phone) {
this.phone = phone;
}
/**
* @return username
*/
public String getUsername() {
return username;
}
/**
* @param username
*/
public void setUsername(String username) {
this.username = username;
}
/**
* @return age
*/
public Integer getAge() {
return age;
}
/**
* @param age
*/
public void setAge(Integer age) {
this.age = age;
}
/**
* @return sex
*/
public String getSex() {
return sex;
}
/**
* @param sex
*/
public void setSex(String sex) {
this.sex = sex;
}
/**
* @return birthday
*/
public Date getBirthday() {
return birthday;
}
/**
* @param birthday
*/
public void setBirthday(Date birthday) {
this.birthday = birthday;
}
@Override
public String toString() {
StringBuilder sb = new StringBuilder();
sb.append(getClass().getSimpleName());
sb.append(" [");
sb.append("Hash = ").append(hashCode());
sb.append(", id=").append(id);
sb.append(", username=").append(username);
sb.append(", age=").append(age);
sb.append(", sex=").append(sex);
sb.append(", birthday=").append(birthday);
sb.append(", phone=").append(phone);
sb.append(", sencode=").append(sencode);
sb.append(", code=").append(code);
sb.append("]");
return sb.toString();
}
}
2.6.Mapper类(使用的通用mapper)
package com.capgemini.dao;
import com.capgemini.domain.User;
import tk.mybatis.mapper.common.Mapper;
@org.apache.ibatis.annotations.Mapper
public interface UserMapper extends Mapper<User> {
}
2.7.Service类
package com.capgemini.service;
import com.capgemini.domain.User;
public interface UserService {
//添加数据
void addUser(User user);
}
2.8.Service实现类
package com.capgemini.service.impl;
import com.capgemini.domain.User;
import org.springframework.stereotype.Service;
import javax.annotation.Resource;
import com.capgemini.dao.UserMapper;
import com.capgemini.service.UserService;
import org.springframework.transaction.annotation.Transactional;
@Service
@Transactional
public class UserServiceImpl implements UserService {
@Resource
private UserMapper userMapper;
//添加用户
@Override
public void addUser(User user) {
userMapper.insert(user);
}
}
2.9.Controller类
package com.capgemini.controller;
import com.capgemini.domain.MyException;
import com.capgemini.domain.User;
import com.capgemini.service.UserService;
import com.capgemini.util.CommonUtil;
import com.capgemini.vo.BaseResult;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
import javax.annotation.Resource;
//@Api 描述类 接口的主要用途
//@ApiOperation 描述方法用途
//@ApiImplicitParam 描述方法的参数
//@ApiImplicitParams 描述方法的参数(Multi-Params)
//@ApiIgnore 忽略某类/方法/参数的文档
@RestController
@RequestMapping("/user")
public class UserController {
@Resource
private UserService userService;
//添加用户
@ApiOperation(value = "创建用户", notes = "根据User对象创建用户")
@ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
@PostMapping
public ResponseEntity<BaseResult> addUser(@RequestBody User user) {
BaseResult br = null;
try {
userService.addUser(user);
br = new BaseResult(CommonUtil.SUCCESS, "添加成功");
} catch (Exception e) {
br = new BaseResult(CommonUtil.FAIL, "添加失败");
}
return new ResponseEntity<>(br, HttpStatus.OK);
}
}
3.访问
http://localhost:9090/swagger-ui.html#/
