swagger的基本用法

       由于工作需要，最近在调试接口的时候，实在让人身心难受加疲惫。现在介绍介绍一个好东西，不再让接口调试那让人欲哭无泪了。相信做过前后端分离的同志，应该都知道这个好东西叫swaager。人狠话不多，直接说怎么使用这个好东西吧。首先我们得创建一个springboot项目，如何创建在这里不再累赘。下面正式进入主题，假如你已经创建好一个springboot的项目。

       第一步，导入swagger的相关jar，具体如下

		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger2</artifactId>
			<version>2.9.2</version>
		</dependency>
		<!--swagger-ui -->
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger-ui</artifactId>
			<version>2.9.2</version>
		</dependency>
		<dependency>
			<groupId>com.google.guava</groupId>
			<artifactId>guava</artifactId>
			<version>26.0-jre</version>
		</dependency>

   第二步，在配置application.properties添加配置spring.swagger2.enabled=true，表示是否开启swagger，一般上生成要关掉，然后写一个配置类，代码如下

@Configuration
@EnableSwagger2
public class SwaggerConfig {
	
	@Value(value = "${spring.swagger2.enabled}")
    private Boolean swaggerEnabled;
	
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(swaggerEnabled)
                .select()
                .apis(RequestHandlerSelectors.basePackage("my"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("接口文档")
                .description("swagger第一个例子")
                .termsOfServiceUrl("")
                .version("1.0")
                .build();
    }

}

   第三步，写一个例子

       1、首先写一个简单的pojo类，

package my.db;

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

@ApiModel(value = "用户信息")
public class User {
	
	@ApiModelProperty(value = "用户ID")
	private Integer id;
	
	@ApiModelProperty(value = "用户名")
	private String username;
	
	@ApiModelProperty(value = "密码")
	private Byte sex;
	
	

	public User() {
		super();
	}
	

	public User(Integer id, String username, Byte sex) {
		super();
		this.id = id;
		this.username = username;
		this.sex = sex;
	}


	public Integer getId() {
		return id;
	}

	public void setId(Integer id) {
		this.id = id;
	}

	public String getUsername() {
		return username;
	}

	public void setUsername(String username) {
		this.username = username;
	}

	public Byte getSex() {
		return sex;
	}

	public void setSex(Byte sex) {
		this.sex = sex;
	}
	

}

 2、写一个controller，

package my.controller;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import my.db.User;

@Api(value = "用户接口")
@RestController
public class UserController {
	
	@ApiOperation("查询用户信息")
	@RequestMapping(value="getUser",method=RequestMethod.GET)
	public User getUser()
	{
		System.out.println("获取用户信息");
		return new User(1001 , "王尼玛" , (byte)1);
	}
	@ApiOperation("添加一条用户")
	@RequestMapping(value="createUser",method=RequestMethod.POST)
	public void createUser(User user)
	{
		System.out.println(user.toString());
	}

}

第四步，写好这些之后，把项目跑起来，然通过连接访问，http://127.0.0.1:8081/swagger-ui.html，端口和IP视情况而定。跑起来后就会访问到这个界面，在这个界面我们直接点get就可以直接访问之前写好的接口，这样让别人调试接口的时候就称心如意了。

写到这里，可能有大伙就问了，swagger是怎么知道哪个接口是干嘛的呀。其实，swagger是通过注解的方式来识别我们写的每个接口，下面是常用的注解：

Swagger 常用注解
注解	用途	注解位置
@Api	描述类的作用	注解于类上
@ApiOperation	描述类的方法的作用	注解于方法上
@ApiParam	描述类方法参数的作用	注解于方法的参数上
@ApiModel	描述对象的作用	注解于请求对象或者返回结果对象上
@ApiModelProperty	描述对象里字段的作用	注解于请求对象或者返回结果对象里的字段上

 这是我springboot学习的开始吧，我以后的学习的代码都会上传到个人的GitHub，https://github.com/Andy147/myspringboot.git上面。算是自己学习的过程的见证吧。