SpringBoot(3) - - SpringBoot整合Swagger2

项目地址:https://github.com/zhaopeng01/springboot-study/tree/master/study3

在后端开发中经常需要对移动客户端提供RESTful API接口，在后期版本快速迭代的过程中，修改接口实现的时候都必须同步修改接口文档，而文档与代码又处于两个不同的媒介，除非有严格的管理机制，不然很容易导致写出的代码与接口文档不一致现象。
为了前后台更好的对接,为了以后交接方便,为了不再长篇大论的手写api文档,那么就来用Swagger吧(不是打广告),它可以轻松的整合到Spring中,它既可以减少我们手写api文档的时间，同时又将说明文档整合到我们的代码中,这样前台看着也方便,后台工作也舒坦,
Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单(其他好处网上自己搜在这里就不再多说了)。
Swagger也提供了强大的页面测试功能来调试每个写好的接口：

其他的不说了，想要了解更多的Swagger优缺点的,自行百度或者去Swagger官网
我们这里说的是使用SpringBoot整合Swagger2来生成接口文档的实现

1.环境

• SpringBoot 2.0.4.RELEASE
• Swagger 2.6.1
• JDK 1.8

2.依赖

    4.0.0

    com.zyc
    mybatis_plus2
    0.0.1-SNAPSHOT
    jar

    Swagger
    Demo project for Spring Boot

    
        org.springframework.boot
        spring-boot-starter-parent
        2.0.4.RELEASE
         
    

    
        UTF-8
        UTF-8
        1.8
    
	
		
	        
	            org.springframework.boot
	            spring-boot-starter-web
	        
		
			io.springfox
			springfox-swagger2
			2.6.1
		
		 
		
			io.springfox
			springfox-swagger-ui
			2.6.1
		
	
	 
	        
	            
	                org.springframework.boot
	                spring-boot-maven-plugin
	            
	        
	    

3.Swagger配置Bean

package com.zyc.config;

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;

/**
*
* @Description:
* @author zp
* @email [email protected]
* @date 2018/8/9 13:49 
*
*/
@Configuration
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.zyc.controller"))
                .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。

启动类中加入@EnableSwagger2 代表swagger开启:

package cn.zyc;
 
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
 
@SpringBootApplication
@EnableSwagger2
public class APP{
 
	public static void main(String[] args) {
		SpringApplication.run(APP.class, args);
	}

4.定义restful接口

package com.zyc.controller;

import com.zyc.model.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;


@RestController
@RequestMapping(value = "/user")
@Api(value = "用户测试模块")
public class UserController {

    @ApiOperation(value = "添加用户", notes = "根据参数添加用户")
    @PostMapping(value = "/add")
    public Object getUser() {
        return new User("zyc", "123123", "1761110");
    }
}

5.实体类

package com.zyc.model;

import java.io.Serializable;

public class User implements Serializable {
    private Integer userId;

    private String userName;

    private String password;

    private String phone;

    public User() {
    }

    public User(String userName, String password, String phone) {
        this.userName = userName;
        this.password = password;
        this.phone = phone;
    }

    public User(Integer userId, String userName, String password, String phone) {
        this.userId = userId;
        this.userName = userName;
        this.password = password;
        this.phone = phone;
    }

    public Integer getUserId() {
        return userId;
    }

    public void setUserId(Integer userId) {
        this.userId = userId;
    }

    public String getUserName() {
        return userName;
    }

    public void setUserName(String userName) {
        this.userName = userName == null ? null : userName.trim();
    }

    public String getPassword() {
        return password;
    }

    public void setPassword(String password) {
        this.password = password == null ? null : password.trim();
    }

    public String getPhone() {
        return phone;
    }

    public void setPhone(String phone) {
        this.phone = phone == null ? null : phone.trim();
    }
}

6.启动

启动项目访问 http://localhost:8080/swagger-ui.html

这个时候,swagger的ui就展现到了你的面前,和上面的图一样

7.Swagger常用注解

- @Api()用于类； 
表示标识这个类是swagger的资源 
- @ApiOperation()用于方法； 
表示一个http请求的操作 
- @ApiParam()用于方法，参数，字段说明； 
表示对参数的添加元数据（说明或是否必填等） 
- @ApiModel()用于类 
表示对类进行说明，用于参数用实体类接收 
- @ApiModelProperty()用于方法，字段 
表示对model属性的说明或者数据操作更改 
- @ApiIgnore()用于类，方法，方法参数 
表示这个方法或者类被忽略 
- @ApiImplicitParam() 用于方法 
表示单独的请求参数 
- @ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam

具体使用举例说明： 
@Api() 
用于类；表示标识这个类是swagger的资源 
tags–表示说明 
value–也是说明，可以使用tags替代 
但是tags如果有多个值，会生成多个list

外话

关于SpringBoot的教程在我之前也有很多大佬写过了,我也是来作为一个个人的笔记来进行记录,如有雷同,还望海涵,希望可以给大家带来帮助 ~ ~&

虚心的去学习,自信的去工作~