第一章 swagger介绍

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整合swagger

3.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);
    }
}