spring boot中使用swagger2构建RESTful风格API

最新推荐文章于 2022-06-27 07:59:27 发布

YingTao8

最新推荐文章于 2022-06-27 07:59:27 发布

阅读量293

点赞数

文章标签： swagger spring boot RESTful

本文链接：https://blog.csdn.net/YingTao8/article/details/83031165

版权

swagger2是什么?

Swagger 是一款RESTful接口的文档在线自动生成+功能测试功能软件。

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。

官网：http://swagger.io/

GitHub地址：https://github.com/swagger-api/swagger-ui

swagger2的作用:

个人觉得，swagger的一个最大的优点是能实时同步api与文档,减少与前端沟通的时间的成本

swagger2在spring boot当中使用:

步骤1:在Pom文件中添加依赖:

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

步骤2:配置Swagger2

编写一个Swagger2的配置类

@Configuration          //让Spring来加载该类配置
@EnableSwagger2         //启用Swagger2
public class Swagger2Config {

    @Bean
    public Docket createRestApi() {
         // DocumentationType.SWAGGER_2  表示使用的是swagger2.0版本
        return new Docket(DocumentationType.SWAGGER_2)    
                .apiInfo(apiInfo())//配置swagger2基本信息
                .select()//返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现
                .apis(RequestHandlerSelectors.basePackage("com.mxx.demo.controller")) //设置swagger2监控的controller,mxx表示通配,扫描到的controller用来产生api文档(除了被@ApiIgnore指定的请求)
                .paths(PathSelectors.any())
            	//.paths(PathSelectors.none())//如果是线上环境，添加路径过滤，设置为全部都不符合
                .build();
    }

    //用来创建swaggerApi的基本信息
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("XXX平台")                              
                .description("对XXX平台的描述！")   
                .termsOfServiceUrl("http://editor.swagger.io/") //服务的网址
                .contact("YYY") //联系人姓名
                .version("1.0") //版本号
                .license("监听")                                   //指定监听名称(就是你想监听啥)
                .licenseUrl("https://www.baidu.com/")             //查看监听内容的网址(可以自己指定，此处为示例)
                .build();                                         //全部构建完成
    }
}

步骤3:编写controller,并在controller上添加swagger2的功能注解

@Api(value="项目信息",description="用来增,删,改,查项目")
@Controller
@RequestMapping("/project")
public class TProjectController {

	@ApiOperation(value="查询项目列表",notes="传入页面信息,以及搜索条件",position=2)
	@ApiImplicitParams({
		@ApiImplicitParam(name="page_no",value="第几页",required=true,paramType="path",dataType="int"),
		@ApiImplicitParam(name="page_size",value="每页显示的数据条数",required=true,paramType="path",dataType="int"),
		@ApiImplicitParam(name="projectName",value="项目名称",required=false,paramType="path",dataType="String")
	})
	@RequestMapping(value="/queryByPage",method=RequestMethod.GET)
	@ResponseBody
	public Page<TProjectEntity> queryByPage(int page_no, int page_size, String projectName, @ApiParam(value="项目编码",required=false)String projectCode) {
		Page<TProjectEntity> page = new Page<>();
		//自己的逻辑代码
        //....

		return page;
	}

	
	@ApiOperation(value="创建项目",notes="根据TProjectEntity对象创建用户",position=1)
	@ApiImplicitParam(name="tProjectEntity",value="项目实体对象",required=true,paramType="body",dataType="TProjectEntity")
	@RequestMapping(value = ("/insert"), method = RequestMethod.POST)
	@ResponseBody
	public ResultMessage insert(TProjectEntity tProjectEntity) {
		ResultMessage resultMessage = new ResultMessage();
		//自己的逻辑代码
        //....
		return resultMessage;
	}
}

@Api:用在controller上,对controller进行说明

value：参数名
description：描述

@ApiOperation:用在方法上,对方法上Url进行说明

value：参数名
notes：描述

@ApiImplicitParam:用在方法上,对方法上单个参数进行说明

name：参数名
dataType：参数类型
required：参数是否必须传
value：参数的描述
defaultValue：参数的默认值
paramType：参数的位置

@ApiImplicitParams:用在方法上,对方法上多个参数进行说明

里边包含多个@ApiImplicitParam

@ApiParam:用在方法参数的变量前,对单个参数进行说明

value：参数名
required：参数是否必须传

@ApiIgnore: 表示该接口函数不对swagger2开放展示

步骤4:启动项目,访问swagger2并且调试