1.1 swagger简介
swagger 是一款RESTFUL接口的文档在线自动生成 功能测试功能软件。
Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许Api来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。
1.2 swagger的由来
- 随着互联网技术的发展，现在的网站架构基本都由原来的后端渲染，变成了：前端渲染、先后端分离的形态，而且前端技术和后端技术在各自的道路上越走越远。
- 前端和后端的唯一联系，变成了API接口；API文档变成了前后端开发人员联系的纽带，变得越来越重要，swagger就是一款让你更好的书写API文档的框架。
官网：http://swagger.io/
GitHub地址：https://github.com/swagger-api/swagger-ui
第二章 swagger2注解
@Api：用在请求的类上，表示对类的说明
tags="说明该类的作用，可以在UI界面上看到的注解"
value="该参数没什么意义，在UI界面上也看到，所以不需要配置"
@ApiOperation：用在请求的方法上，说明方法的用途、作用
value="说明方法的用途、作用"
notes="方法的备注说明"
@ApiParam：用于方法，参数，字段说明，表示对参数的添加元数据（说明或是否必填等）
name:属性名称
value：属性值
defaultValue：默认属性值
required：是否属性必填
example：举例子
@ApiImplicitParams：用在请求的方法上，表示一组参数说明
@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
name：参数名
value：参数的汉字说明、解释
required：参数是否必须传
paramType：参数放在哪个地方
· header --> 请求参数的获取：@RequestHeader
· query --> 请求参数的获取：@RequestParam
· path（用于restful接口）--> 请求参数的获取：@PathVariable
· body（不常用）
· form（不常用）
dataType：参数类型，默认String，其它值dataType="Integer"
defaultValue：参数的默认值
@ApiResponses：用在请求的方法上，表示一组响应
@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
code：数字，例如400
message：信息，例如"请求参数没填好"
response：抛出异常的类
@ApiModel：用于响应类上，表示一个返回响应数据的信息
（这种一般用在post创建的时候，使用@RequestBody这样的场景，
请求参数无法使用@ApiImplicitParam注解进行描述的时候）
@ApiModelProperty：用在属性上，描述响应类的属性
2.1 @Api
用在请求的类上，说明该类的作用
@Api：用在请求的类上，说明该类的作用
tags="说明该类的作用"
value="该参数没什么意义，所以不需要配置"
示例 @Api(tags="APP用户注册Controller")
2.2 @ApiOperation
用在请求的方法上，说明方法的作用
@Apioperation："用在请求的方法上，说明方法的作用"
value="说明方法的作用"
notes="方法的备注说明"
示例 @ApiOperation(value="用户注册",notes="手机号、密码都是必输项，年龄随边填，但必须是数字")
2.3 @ApiParam
与Controller中的方法并列使用
示例
@ApiOperation(value = "传设置过期时间")
@RequestMapping(value = "/expire", method = RequestMethod.POST)
public boolean expire(
@ApiParam(name = "key", value = "cache key", required = true) @RequestParam("key") String key,
@ApiParam(name = "expireSecond", value = "key过期时间:秒", required = true) @RequestParam("expireSecond") Integer expireSecond){
checkParams(key);
log.info("key:{},", key);
return redisservice.expire(key, expireSecond);
}
2.4 @ApiImplicitParams
用在请求的方法上，包含一组参数说明
@ApiImplicitParams：用在请求的方法上，包含一组参数说明
@ApiImplicitParam：用在 @ApiImplicitParams 注解中，指定一个请求参数的配置信息
name：参数名
value：参数的汉字说明、解释
required：参数是否必须传
paramType：参数放在哪个地方
· header --> 请求参数的获取：@RequestHeader
· query --> 请求参数的获取：@RequestParam
· path（用于restful接口）--> 请求参数的获取：@PathVariable
· body（不常用）
· form（不常用）
dataType：参数类型，默认String，其它值dataType="Integer"
defaultValue：参数的默认值
示例
@ApiImplicitParams({
@ApiImplicitParam(name="mobile",value="手机号",required=true,paramType="form"),
@ApiImplicitParam(name="password",value="密码",required=true,paramType="form"),
@ApiImplicitParam(name="age",value="年龄",required=true,paramType="form",dataType="Integer")
})
2.5 @ApiResponses
用于请求的方法上，表示一组响应
@ApiResponses：用于请求的方法上，表示一组响应
@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
code：数字，例如400
message：信息，例如"请求参数没填好"
response：抛出异常的类
示例
@ApiOperation(value = "select1请求",notes = "多个参数，多种的查询参数类型")
@ApiResponses({
@ApiResponse(code=400,message="请求参数没填好"),
@ApiResponse(code=404,message="请求路径没有或页面跳转路径不对")
})
2.6 @ApiModel
用于响应类上，表示一个返回响应数据的信息
@ApiModel：用于响应类上，表示一个返回响应数据的信息
（这种一般用在post创建的时候，使用@RequestBody这样的场景，
请求参数无法使用@ApiImplicitParam注解进行描述的时候）
@ApiModelProperty：用在属性上，描述响应类的属性
示例
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import java.io.Serializable;
@ApiModel(description= "返回响应数据")
public class RestMessage implements Serializable{
@ApiModelProperty(value = "是否成功")
private boolean success=true;
@ApiModelProperty(value = "返回对象")
private Object data;
@ApiModelProperty(value = "错误编号")
private Integer errCode;
@ApiModelProperty(value = "错误信息")
private String message;
/* getter/setter */
}
在完成了上述配置后，其实已经可以生产文档内容，但是这样的文档主要针对请求本身，描述的主要来源是函数的命名，对用户并不友好，我们通常需要自己增加一些说明来丰富文档内容。
第三章 SpringBoot整合swagger3.1 环境搭建
略
3.2 创建数据库以及表
CREATE TABLE `book` (
`id` bigint(20) NOT NULL AUTO_INCREMENT,
`name` varchar(50) NOT NULL COMMENT '图书名称',
`author` varchar(10) DEFAULT NULL COMMENT '作者',
`price` decimal(10,0) DEFAULT NULL,
`publish_date` datetime DEFAULT NULL,
PRIMARY KEY (`id`)
) ENGINE=InnoDB AUTO_INCREMENT=4 DEFAULT CHARSET=utf8;
/*Data for the table `book` */
insert into `book`(`id`,`name`,`author`,`price`,`publish_date`) values (1,'天龙八部','金庸',250,'2018-03-20 08:00:00');
3.3 添加依赖
<!--依赖管理父节点的配置，简化maven的依赖管理-->
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>2.0.3.RELEASE</version>
<relativePath/> <!-- lookup parent from repository -->
</parent>
<groupId>com.qianfeng.springboot</groupId>
<artifactId>swagger</artifactId>
<version>0.0.1-SNAPSHOT</version>
<name>demo</name>
<description>Demo project for Spring Boot</description>
<properties>
<java.version>1.8</java.version>
</properties>
<!--配置启动依赖和其他依赖-->
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>mysql</groupId>
<artifactId>mysql-connector-java</artifactId>
<version>5.1.47</version>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-devtools</artifactId>
<optional>true</optional>
</dependency>
<!--swagger2 依赖-->
<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>
</dependencies>
<!--配置maven插件：可以用maven的形式启动Spring Boot项目（另外也可以在主方法中启动）-->
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
3.4 springboot的配置文件
application.yml
# 服务端口配置
server:
port: 8088
# mysql配置
spring:
datasource:
driver-class-name: com.mysql.jdbc.Driver
url: jdbc:mysql://127.0.0.1:3306/order?useUnicode=true&characterEncoding=utf-8
username: root
password: weizhigang
# 日志配置
logging:
level:
root: info
# swagger配置
swagger:
basePackage: com.qianfeng.springboot.swagger
title: 图书管理平台API
description: 书店平台的REST API，所有应用程序都可以通过JSON访问对象模型数据。
contact: qianfeng
version: v1.0
url: http://www.1000phone.com
3.5 创建swagger2的配置类
package com.qianfeng.springboot.swagger.config;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ViewControllerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
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;
/**
* Created by liliting on 18/3/14.
*/
@Configuration
@EnableSwagger2
public class SwaggerConfig implements WebMvcConfigurer {
@Value("${swagger.basePackage}")
private String basePackage;// 扫描controler的包名
@Value("${swagger.title}")
private String title;// 在线文档的标题
@Value("${swagger.description}")
private String description;// 在线文档的描述
@Value("${swagger.contact}")
private String contact;// 联系人
@Value("${swagger.version}")
private String version;// 文档版本
@Value("${swagger.url}")
private String url;// URL
@Bean
public Docket createApi() {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()// 函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现
.apis(RequestHandlerSelectors.basePackage(basePackage)).paths(PathSelectors.any()).build();
}
/**
* apiInfo()用来创建该Api的基本信息
* </p>
* 这些基本信息会展现在文档页面中
*
* @return
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder().title(title).description(description).version(version).contact(contact).licenseUrl(url)
.build();
}
/**
* swagger-ui.html路径映射，浏览器中使用/api-docs访问
* @param registry
*/
@Override
public void addViewControllers(ViewControllerRegistry registry) {
// 添加服务api访问文档url
registry.addRedirectViewController("/api", "/swagger-ui.html");
}
}
如上代码所示，通过createApi函数创建Docket的Bean之后，apiInfo()用来创建该Api的基本信息（这些基本信息会展现在文档页面中）。
3.6 编写Controller
package com.qianfeng.springboot.swagger.config;
import com.itqf.pojo.Book;
import com.itqf.service.BookService;
import org.springframework.web.bind.annotation.*;
import javax.annotation.Resource;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
/**
* Created by liliting on 18/3/14.
*/
//@Controller
@RestController //Controller ResponseBody
@RequestMapping("/api1")
public class BookController {
@Resource
private BookService bookService;
@RequestMapping("/findAll")
public List<Book> findAll()
{
System.out.print(111);
return bookService.findAll();
}
@PostMapping("/saveBook")
public Book save(@RequestBody Book book){//json --》 对象
bookService.saveBook(book);
System.out.println(book);
return book;
}
@PutMapping("/updateBook")
public Book update(Book book){
bookService.update(book);
return book;
}
@DeleteMapping("/deleteBook")
public Map delete(int id){
Map map = new HashMap();
try{
bookService.delete(id);
map.put("result","success");
}catch (Exception e){
map.put("result","fail");
}
return map;
}
}
3.7 pojo
package com.itqf.pojo;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import javax.persistence.Entity;
import javax.persistence.GeneratedValue;
import javax.persistence.GenerationType;
import javax.persistence.Id;
import java.util.Date;
/**
* Created by liliting on 18/3/14.
*/
@Entity
@ApiModel(value = "图书对象",description = "对应图书表")
public class Book {
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
@ApiModelProperty(name="id",example = "1")
private int id;
@ApiModelProperty(name="name",example = "天龙八部")
private String name;
@ApiModelProperty(name="author",example = "金庸")
private String author;
@ApiModelProperty(name="price",example = "250.0")
private double price;
@ApiModelProperty(name="publishDate",example = "2018-03-20")
private Date publishDate;
public int getId() {
return id;
}
public void setId(int id) {
this.id = id;
}
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
public String getAuthor() {
return author;
}
public void setAuthor(String author) {
this.author = author;
}
public double getPrice() {
return price;
}
public void setPrice(double price) {
this.price = price;
}
public Date getPublishDate() {
return publishDate;
}
public void setPublishDate(Date publishDate) {
this.publishDate = publishDate;
}
}
3.8 controller
package com.itqf.controller;
import com.itqf.pojo.Book;
import com.itqf.service.BookService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.*;
import javax.annotation.Resource;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
/**
* Created by liliting on 18/3/14.
*/
//@Controller
@RestController //Controller ResponseBody
@RequestMapping("/api1")
@Api(description = "图书管理api",value = "管理图书")
public class BookController {
@Resource
private BookService bookService;
@ApiOperation(value = "查询所有图书")
@GetMapping("/findAll")
public List<Book> findAll()
{
return bookService.findAll();
}
@ApiOperation(value = "新增图书")
@PostMapping("/saveBook")
public Book save(@ApiParam(value = "图书对象") @RequestBody Book book){//json --》 对象
bookService.saveBook(book);
return book;
}
@ApiOperation(value = "修改图书",response = Book.class)
@PutMapping("/updateBook")
public Book update(@ApiParam(value = "图书对象") Book book){
bookService.update(book);
return book;
}
@ApiOperation(value = "删除图书")
@DeleteMapping("/deleteBook")
public Map delete(@ApiParam(required = true,value ="图书编号") int id){
Map map = new HashMap();
try{
bookService.delete(id);
map.put("result","success");
}catch (Exception e){
map.put("result","fail");
}
return map;
}
}
3.9 dao层
package com.qianfeng.springboot.swagger.config;
import com.itqf.pojo.Book;
import org.springframework.data.jpa.repository.JpaRepository;
/**
* Created by liliting on 18/3/14.
*/
public interface BookDaoImpl extends JpaRepository<Book,Integer> {
}
3.10 service层
3.10.1 接口
package com.qianfeng.springboot.swagger.config;
import com.itqf.pojo.Book;
import java.util.List;
import java.util.Optional;
/**
* Created by liliting on 18/3/14.
*/
public interface BookService {
public List<Book> findAll();
public Book findById(int id);
public void saveBook(Book book);
public void update(Book book);
public void delete(int id);
}
3.10.2 实现类
package com.qianfeng.springboot.swagger.config;
import com.itqf.dao.impl.BookDaoImpl;
import com.itqf.pojo.Book;
import com.itqf.service.BookService;
import org.springframework.stereotype.Service;
import javax.annotation.Resource;
import java.util.List;
import java.util.Optional;
/**
* Created by liliting on 18/3/14.
*/
@Service
public class BookServiceImpl implements BookService {
@Resource
private BookDaoImpl bookDaoImpl;
@Override
public List<Book> findAll() {
return bookDaoImpl.findAll();
}
@Override
public Book findById(int id) {
return bookDaoImpl.findOne(id);
}
@Override
public void saveBook(Book book) {
bookDaoImpl.save(book);
}
@Override
public void update(Book book) {
bookDaoImpl.saveAndFlush(book);
}
@Override
public void delete(int id) {
bookDaoImpl.delete(id);
}
}
3.11 启动类
package com.qianfeng.springboot.swagger;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication
public class SpringbootSwaggerApplication {
public static void main(String[] args) {
SpringApplication.run(SpringbootSwaggerApplication.class, args);
}
}
