swagger在springboot上的快速上手

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

首先,在pom文件引入如下依赖位置:

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

首先,创建Swagger配置类

package com.example.demo.swagger2;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;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/*swagger2的配置类@Configuration使spring加载此类@EnableSwagger2启用swagger2*/
@Configuration
@EnableSwagger2
public class Swagger2 {/*** 创建API应用* 通过select（）函数返回ApiSelectorBuilder实例，用来控制哪些接口暴露给swagger来展现* 这里使用指定包路径来展示* @return*/@Beanpublic Docket createRestApi(){return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.basePackage("com.example.demo.swagger2")).paths(PathSelectors.any()).build();}/*** 该方法主要配置一些api的基本信息（会展示）* 访问地址：http://项目实际地址/swagger-ui.html* @return*/private ApiInfo apiInfo(){return new ApiInfoBuilder().title("springboot 使用swagger2构建 RestApis").description("更多请关注https://mp.csdn.net/postedit/84584783").termsOfServiceUrl("https://mp.csdn.net/postedit/84584783").contact("han").version("1.0").build();}
}

接下来,我们来看看常用的注解

@Api:用在类上说明,此类的作用

@ApiOperation:用在方法上说明,此方法的作用

@ApiImplicitParams:用在方法上包含一组参数说明

@ApiImplicitParam:用来注解来给方法入参说明

-- paramType:指定参数放在请求的那个地方

--header:请求参数放置于Request Header,使用@RequestHeader获取

-- query:请求参数放置于请求地址,使用@RequestParam获取

-- path:请求参数放置于url地址栏,使用@PathVariable获取(restful接口)

-- body:请求参数放置于请求体

-- form:请求参数以表单形式放置

-- name:参数名

-- value:参数说明

-- required:参数是否必传

-- dataType:参数类型

-- defaultValue:默认的参数值

以下是参数为基本类型的示例:

package com.example.demo.swagger2;import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.stereotype.Controller;
import org.springframework.util.StringUtils;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.ResponseBody;@Controller
@Api(value = "SwaggerController|一个用来测试swagger的控制类",tags = {"测试swagger类"})
@RequestMapping("/swagger")
public class SwaggerController {@ResponseBody@RequestMapping(value = "/getName",method = RequestMethod.GET)@ApiOperation(value = "根据用户id获取用户名称",notes = "test:请勿传入汉字,且不能大于2")@ApiImplicitParam(paramType = "query",name = "userId",value = "用户id",required = true,dataType = "Integer")public String getName(@RequestParam Integer userId){if (userId == 1){return "杨雪";} else if (userId == 2) {return "杨胖";} else {return "杨猪";}}@ResponseBody@RequestMapping(value = "/updatePassword",method = RequestMethod.GET)@ApiOperation(value = "根据用户id,修改用户密码",notes = "Test:id不能大于2")@ApiImplicitParams({@ApiImplicitParam(paramType = "query",name = "userId",value = "用户id",required = true,dataType = "Integer"),@ApiImplicitParam(paramType = "query",name = "password",value = "旧密码",required = true,dataType = "String"),@ApiImplicitParam(paramType = "query",name = "newPassword",value = "新密码",required = true,dataType = "String")})public String updatePassword(@RequestParam(value = "userId") Integer userId,@RequestParam(value = "password") String password,@RequestParam(value = "newPassword") String newPassword){if (userId >= 2 || userId <= 0) {return "不认识的";}if (StringUtils.isEmpty(password) || StringUtils.isEmpty(newPassword)) {return "密码不能为空";}if (password.equals(newPassword)) {return "新旧密码不能相同";}return "密码修改成功";}
}

完成上述代码添加上，启动Spring Boot程序，访问：http://localhost:8080/swagger-ui.html

如上图,我们可以在生成的文档上直接对代码进行测试,此处类似使用postman,就不在赘述了.

最后,我们来看下如果接收的参数是对象如何接收:

@ApiModel:用在pojo类上,对类进行说明

@ApiModelProperty:用在pojo类的属性上,对属性进行注入

下面直接上示例:

package com.example.demo.swagger2;import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;@Data
@ApiModel(value = "医生对象模型")
public class Doctor {@ApiModelProperty(value = "id",required = true)private Integer id;@ApiModelProperty(value = "name",required = true)private String name;
}

package com.example.demo.swagger2;import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.ResponseBody;
import org.springframework.web.client.HttpStatusCodeException;@Controller
@RequestMapping("/doctorSwagger")
@Api(value = "医生信息接口模拟")
public class DoctorSwaggerController {@RequestMapping(value = "/addDoctor",method = RequestMethod.POST)@ResponseBody@ApiOperation(value = "添加医生信息",notes = "直接添加对象")public String addDoctor(@RequestBody Doctor doctor) throws Exception{if (doctor == null || doctor.getId() == null)throw new Exception("添加医生信息失败,实体为null");try {System.out.println("添加医生信息成功"+doctor.getName());} catch (Exception e) {throw new Exception("添加医生信息失败,原因未知");}return doctor.getId().toString();}
}

此处需注意的是swagger自带的工具采用的是json传参,测试时需要在参数上加上@ResponseBody,正常运行使用form或URL时,删除即可.

swagger在springboot上的快速上手相关推荐

Springboot+Mybatis接口快速上手
这个作业属于哪个课程软件工程实践2022年春-F班这个作业要求在哪里软件工程实践总结&个人技术博客这个作业的目标个人技术博客其他参考文献 CSDN.博客园目录一.技术概述二. ...
OSX上Docker快速上手－以部署node.js环境为例
Docker简介 Docker 是一个开源的应用容器引擎,让开发者可以打包他们的应用以及依赖包到一个可移植的容器中,然后发布到任何流行的 Linux 机器上,也可以实现虚拟化. docker的英文本意 ...
一、快速上手SpringBoot
一.快速上手SpringBoot 一.快速上手SpringBoot 1.SpringBoot快速入门(一) 2.SpringBoot快速入门(二) 3.SpringBoot快速入门(三) 4.Spri ...
快速上手Springboot项目（登录注册保姆级教程）
本文章对SpringBoot开发后端项目结构做了简单介绍,并示范了使用SpringBoot+MySQL实现登录的后端功能,与本博客的另一篇文章 Vue 实现登录注册功能(前后端分离完整案例) | Ma ...
【快速上手系列】使用Springboot集成Swagger2的简单使用测试
[快速上手系列]使用Springboot集成Swagger2的简单使用测试简介 Swagger2是为了解决企业中接口(api)中定义统一标准规范的文档生成工具. 尤其是前后端分离时对一些业务接口也不 ...
上传文件微信小程序input_快速上手微信小程序UI框架
本课程属于微信小程序 A计划,不单独售卖,加入 A 计划可免费观看本课程及所有微信小程序收费课程~ 微信小程序 A计划永久有效期购买链接: http://www.sikiedu.com/clas ...
快速上手Arduino -- 打印超声波模块测距信息到OLED屏幕上
文章目录快速上手Arduino -- 打印超声波模块测距信息到OLED屏幕上实现效果: 模块说明: 引脚接线方法: 程序源码附录快速上手Arduino – 打印超声波模块测距信息到OLED屏幕 ...
【opencv入门篇】 10个程序快速上手opencv【上】
导言:本系列博客目的在于能够在vs快速上手opencv,理论知识涉及较少,大家有兴趣可以查阅其他博客深入了解相关的理论知识,本博客后续也会对图像方向的理论进一步分析,敬请期待:) PS:官方文档永远是 ...
【Scala教程】如何在已掌握的Java知识基础上快速上手Scala？【个人学习记录】
如何在已掌握的Java知识基础上学习Scala 前言正文开始! 1. 编译运行 2. 声明变量 3. 输出 4. 显式指定变量类型 5. 范围区间 6. 写入文本文件 7. 读取文本文件 8. if ...

swagger在springboot上的快速上手

swagger在springboot上的快速上手相关推荐

最新文章

热门文章