SpringBoot（二十四）集成Swagger2

SpringBoot版本：2.1.1

拿前面这篇博客做测试，有现成的接口（传送门），记得前面接口写好了是用postman测试，今天写完就不需要用postman进行测试了。 直接用Swagger2来生成在线接口文档和测试服务。

先截图观摩一下，我个人觉得这个还是可以的，因为我就是处于前后分离的开发模式，要写接口文档。

废话不多说了

1、先添加依赖

    <!--swagger2 -->
	<dependency>
	    <groupId>io.springfox</groupId>
	    <artifactId>springfox-swagger2</artifactId>
	    <version>2.8.0</version>
	</dependency>
	<dependency>
	    <groupId>io.springfox</groupId>
	    <artifactId>springfox-swagger-ui</artifactId>
	    <version>2.8.0</version>
	</dependency>

2、接着是配置类

这个配置配置好了以后也不用怎么改的

package com.eastcom.swagger;

import org.springframework.beans.factory.annotation.Value;
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;

@Configuration
public class SwaggerConfig {
	
	@Value("${swagger.enabled}")
	private boolean swaggerEnabled;
	
	@Bean
	public Docket docket() {
		return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
                // 是否开启
                .enable(swaggerEnabled)
                .select()
                // 扫描的路径包
                .apis(RequestHandlerSelectors.basePackage("com.eastcom.controller"))
                // 指定路径处理PathSelectors.any()代表所有的路径
                .paths(PathSelectors.any())
                .build();
	}
	
	private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("SpringBoot集成和使用Swagger2-demo示例")
                .description("yb")
                // 作者信息
                .contact(new Contact("天黑黑", "https://blog.csdn.net/yhahaha_", "1164755239@qq.com"))
                .version("1.0.0")
                .build();
    }
}

3、添加文档内容

就用前面整合mybatis的时候写的接口。

@Controller
@RequestMapping("/jdbc")
@Api(tags="接口文档")
public class DetpController {
	
	@Autowired
	private DeptDao deptDao;
	
	@RequestMapping(value="/select",method=RequestMethod.GET,produces=MediaType.APPLICATION_JSON_VALUE)
	@ApiOperation(value="查询(ID)")    
    @ApiImplicitParam(name="id",value="查询ID",required=true)
	public ResponseEntity<JsonResult> selectById(Integer id){
		JsonResult result = new JsonResult();
		try {
			Dept data = deptDao.selectByPrimaryKey(id);
			result.setData(data);
			result.setStatus(Status.OK);
		} catch (Exception e) {
			result.setStatus(Status.ERROR);
			result.setData(e.getClass()+":"+e.getMessage());
			e.printStackTrace();
		}
		return ResponseEntity.ok(result); 
	}
	
	//@RequestBody:把接收到的json字符串自动转换为所对应的对象
	/**
	 * @param dept  { "deptno":"60", "dname":"开发", "location":"上海" }
	 * @return
	 */
	@PostMapping(value="/insert")
	@ApiOperation(value="新增")
	public ResponseEntity<JsonResult> insert(@RequestBody Dept dept){
		JsonResult result = new JsonResult();
		try {
			Integer insert = deptDao.insertSelective(dept);
			result.setData(insert);
			result.setStatus(Status.OK);
		} catch (Exception e) {
			result.setStatus(Status.ERROR);
			result.setData(e.getClass()+":"+e.getMessage());
			e.printStackTrace();
		}
		return ResponseEntity.ok(result); 
	}
	
	@PostMapping(value="/update")
	@ApiOperation(value="修改")
	public ResponseEntity<JsonResult> update(@RequestBody ParamDto dto){
		JsonResult result = new JsonResult();
		try {
			System.out.println("dto:"+ dto.toString());
			
			DeptExample example = new DeptExample();
			example.createCriteria().andDeptnoEqualTo(dto.getId());
			Integer update = deptDao.updateByExampleSelective(dto.getDept(), example);

			result.setData(update);
			result.setStatus(Status.OK);
		} catch (Exception e) {
			result.setStatus(Status.ERROR);
			result.setData(e.getClass()+":"+e.getMessage());
			e.printStackTrace();
		}
		return ResponseEntity.ok(result); 
	}
	
	@PostMapping(value="/delete")
	@ApiOperation(value="删除")
	public ResponseEntity<JsonResult> delete(@RequestParam("id") String id,HttpServletRequest request){
		JsonResult result = new JsonResult();
		try {
			DeptExample example = new DeptExample();
			example.createCriteria().andDeptnoEqualTo(Integer.parseInt(id));
			Integer delete = deptDao.deleteByExample(example);

			result.setData(delete);
			result.setStatus(Status.OK);
		} catch (Exception e) {
			result.setStatus(Status.ERROR);
			result.setData(e.getClass()+":"+e.getMessage());
			e.printStackTrace();
		}
		return ResponseEntity.ok(result); 
	}

}

实体类

@ApiModel
public class Dept {
	@ApiModelProperty(value="部门编号",dataType="Integer",name="deptno")
    private Integer deptno;
	
	@ApiModelProperty(value="部门名称",dataType="String",name="dname")
    private String dname;
	
	@ApiModelProperty(value="所在地",dataType="String",name="location")
    private String location;

    //get和set省略...
}

最后在启动类上添加注解@EnableSwagger2

4、使用

在浏览器里输入http://localhost:8080/swagger-ui.html，就是上面最开始看到的截图效果了。

先看下实体类的效果，字段类型和说明都有了。

再来看接口，点击Try it out。

再看下查询的接口，操作就跟上面是一样的了，同样是点击Try it out，再点Execute。

后面的就不一一演示了，最后说一下上面用到的注解

Api：用在类上，说明该类的作用，用在controller上，效果上面也看到了，就是一些说明信息。

ApiModel：这个用在实体类上，描述一个Model的信息

ApiModelProperty：描述一个model的属性，这个效果上面也看到了，字段说明。

ApiOperation：用在方法上，说明方法作用。

当然每个注解还有其他属性，就不一一说明了，这里推荐个文章，里面详细说明了==》传送门