Swagger2快速入门

---

前言

随着前后端分离项目的流行，api文档是最好的沟通方式，Swagger2可以快速生成api文档

一、Swagger2是什么？

Swagger2是一个规范和完整的框架，用于生成、描述、调用，可视化RESTFul风格和web服务。
1、及时性：接口变更后，能够及时准确的通知相关前后端开发人员。
2、规范性：保证接口的规范性，如接口地址、请求方式、参数及响应格式、错误信息。
3、一致性：接口信息一致，不会出现因开发人员拿到的文档版本不一致，而出现分歧。
4、可测性：直接在接口文档上进行测试，以便理解业务。

二、使用Swagger2

1、引入依赖

导入Swagger2和Swagger-ui和swagger-bootstrap-ui依赖：

<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger2</artifactId>
	<version>2.9.2</version>
</dependency>
//可视化页面地址: localhost:prot/swagger-ui.html
<dependency>
	<groupId>io-springfox</groupId>
	<artifactId>springfox-swagger-ui</artifactId>
	<version>2.9.2<version>
</dependency>
//可视化页面地址: localhost:prot/doc.html
<dependency>
	<groupId>com.github.xiaoymin<groupId>
	<artifactId>swagger-bootstrap-ui</artifactId>
	<version>1.9.6</version>
</dependency>

springfox-swagger-ui或swagger-bootstrap-ui导入一个即可。

2、配置Swagger2

新建一个配置类Swagger2Config

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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

//表明该类是一个配置类
@Configuration
//开启Swagger2
@EnableSwagger2
public Config Swagger2Cofig(){
	//创建一个Docket对象的Bean
	@Bean
	public Docket webApiDocket(){
		//DocumentationType选择配置文件类型SWAGGER_2
		retuen Docket(DocumentationType.SWAGGER_2)
				//添加信息
				.addInfo(webApiInfo())
				//设置分组
				.groupName("分组名")
				//Docket的select()方法会提供一个默认构造器（ApiSelectorBuilder),这个构造器为配置swagger提供了一系列的默认属性和便利方法。
				.select()
				//扫描路径
				//RequestSelector参数:any-扫描所有,basePackage：指定包路径,none-不扫描
				.api(RequestSelectors.any)
				//过滤路径，PathsSelector.ant：指定过滤路径
				.paths(PathSelectors.any)
				//Docket构建
				.build();
	}
	
	public ApiInfo webApiInfo(){
		return new ApiInfoBuilder()
					//标题
					.title("标题名")
					//描述
					.descroption("Api文档")
					//版本
					.version("1.0")
					//作者信息
					.contact("名字","服务器路径","邮箱")
					.build();
	}
}

---

配置swagger2好，即可用访问localhost:prot/swagger-ui.html 或 localhost:prot/doc.html，访问成功则会有页面显示。

三、Swagger2常用注解

@Api：类的说明
		tag：说明类的作用	
		description：类的描述
@ApiOperation：方法的说明
		value：说明方法的作用
		notes：方法的备注说明
@ApilmplicitParams @ApilmplicitParam：参数的说明，用于指定单个参数的说明
		paramType：获取参数的方式
		name：参数名	
		vlue：参数的描述
		dataType：参数的类型
@ApiResponses @ApiResponse：返回值的说明，用于指定单个返回值的说明
		code：方法返回值的状态码
		message：信息
		response：抛出的异常类
@ApiModel：JavaBean的说明
		description：对api资源的描述
@@ApiModelProperty	JavaBean属性的说明
		value：属性描述

四、测试注解

Controll类

import com.example.demo.pojo.Student;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RestController;

@Api(tags ="SwaggerContoller控制器" )
@RestController
public class SwaggerController {

    @ApiOperation(value = "查询Swagger",notes = "返回名字，密码")
    @GetMapping("/dome/{uName}/{uPassword}")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType = "path",name = "uName",value = "姓名",required = true,dataType = "String" ),
            @ApiImplicitParam(paramType = "path",name="uPassword",value="密码")
    })
    
    @ApiResponse(code = 400,message = "参数没填",reference = "NullPointerException")
    public Student queSwagger(@PathVariable(value = "uName",required = true) String uName, @PathVariable(value = "uPassword",required = false) String uPassword){
        Student student = new Student();
        student.setName(uName);
        student.setPassword(uPassword);
        return student;
    }
}

POJO类

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel("学生类")
public class Student {

    @ApiModelProperty("姓名")
    private String name;
    
    @ApiModelProperty("密码")
    private String password;

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getPassword() {
        return password;
    }

    public void setPassword(String password) {
        this.password = password;
    }
}

五、访问可视化页面

访问localhost:prot/doc.html