Swagger 01 入门
Swagger
一、Swagger工作原理
在项目启动的过程中，spring上下文在初始化的过程，框架自动跟据配置加载一些swagger相关的bean到当前的上下文中，并自动扫描系统中可能需要生成api文档那些类，并生成相应的信息缓存起来。如果项目MVC控制层用的是springMvc那么会自动扫描所有Controller类，跟据这些Controller类中的方法生成相应的api文档。
二 、swagger常用注解简述
1、@Api
描述：注解用于标注一个Controller（Class），加入@Api即标识能被scan
属性值：
| 属性 | 描述 |
|---|---|
| value | url的路径值 |
| tags | 如果设置这个值、value的值会被覆盖 |
| description | 对api资源的描述 |
| basePath | 基本路径可以不配置 |
| position | 如果配置多个Api 想改变显示的顺序位置 |
| produces | For example, “application/json, application/xml” |
| consumes | For example, “application/json, application/xml” |
| protocols | Possible values: http, https, ws, wss. |
| authorizations | 高级特性认证时配置 |
| hidden | 配置为true 将在文档中隐藏 |
参考：
@RestController( value= "swaggerController")
@RequestMapping(name="swaggerController", path = "/swagger")
@Api(value = "SwaggerTest",produces = "application/json, application/xml",consumes = "application/json, application/xml",protocols = "http",hidden = false)
public class SwaggerController {2、@ApiOperation
描述：@ApiOperation 注解在用于对一个操作或HTTP方法进行描述。具有相同路径的不同操作会被归组为同一个操作对象。不同的HTTP请求方法及路径组合构成一个唯一操作。
属性值：
| 属性 | 描述 |
|---|---|
| value | url的路径值 |
| tags | 如果设置这个值、value的值会被覆盖 |
| description | 对api资源的描述 |
| basePath | 基本路径可以不配置 |
| position | 如果配置多个Api 想改变显示的顺序位置 |
| produces | For example, “application/json, application/xml” |
| consumes | For example, “application/json, application/xml” |
| protocols | Possible values: http, https, ws, wss. |
| authorizations | 高级特性认证时配置 |
| hidden | 配置为true 将在文档中隐藏 |
| response | 返回的对象 |
| responseContainer | 这些对象是有效的 “List”, “Set” or “Map”.，其他无效 |
| httpMethod | “GET”, “HEAD”, “POST”, “PUT”, “DELETE”, “OPTIONS” and “PATCH” |
| code | http的状态码 默认 200 |
| extensions | 扩展属性 |
参考：
@GetMapping(name="sayHi",value = "/sayHi")
@ApiOperation(value="sayHi",httpMethod = "GET",code=200,response = java.lang.String.class,protocols = "http")
public String sayHi(){return "Hello Swagger";
}
3、@ApiParam
描述：@ApiParam作用于请求方法上，定义api参数的注解。
属性值：
| 属性 | 描述 |
|---|---|
| name | 属性名称 |
| value | 属性值 |
| defaultValue | 默认属性值 |
| allowableValues | 可以不配置 |
| required | 是否属性必填 |
| access | 不过多描述 |
| allowMultiple | 默认为false |
| hidden | 隐藏该属性 |
| example | 举例子 |
参考：
@ApiOperation(value = "getUserName",httpMethod = "POST",code = 200)
public String getUserName(@ApiParam(name = "username",value = "用户名" , required = true , example = "tab") @RequestParam String username){return username;
}
4、@ApiImplicitParams、@ApiImplicitParam
描述：@ApiImplicitParams用在请求方法上对一组参数的说明，@ApiImplicitParam用在请求方法上对单个参数的说明
属性值： @ApiImplicitParams的属性值 只有 @ApiImplicitParam数组
| 属性 | 描述 |
|---|---|
| name | 参数名 |
| value | 参数的说明、描述 |
| required | 参数是否必须必填 |
| paramType | 参数放在哪个地方 query --> 请求参数的获取：@RequestParam header --> 请求参数的获取：@RequestHeader path（用于restful接口）–> 请求参数的获取：@PathVariable body（请求体）–> @RequestBody User user form（普通表单提交） |
| dataType | 参数类型，默认String，其它值dataType=“Integer” |
| defaultValue | 参数的默认值 |
参考：
@GetMapping(name ="getUserPassword" , value="/getUserPassword")
@ApiOperation(value = "getUserPassword",httpMethod = "GET")
@ApiImplicitParams({@ApiImplicitParam( name="password", value = "密码" , required = true , dataType = "Integer" , allowableValues = "1,2,3")})
public String getUserPassword( @RequestParam String password){return "this is a "+password;
}
5、@ApiResponses、@ApiResponse
描述：@ApiResponses、@ApiResponse进行方法返回对象的说明。
属性值：
| 属性 | 描述 |
|---|---|
| code | 数字，例如400 |
| message | 信息，例如"请求参数没填好" |
| response | 自定义的schema的实体类 |
参考：总体感觉没啥用
@GetMapping(name ="setResponseInfo" , value="/setResponseInfo")
@ApiOperation(value = "setResponseInfo",httpMethod = "GET")
@ApiImplicitParams({@ApiImplicitParam( name="name", value = "名称" , required = true )})
@ApiResponses({@ApiResponse(code = 200,message = "请求成功"),@ApiResponse(code = 400,message = "请求参数异常")})
public String setResponseInfo( @RequestParam String name){return "Hi "+name;
}
6、@ApiModel、@ApiModelProperty
描述：@ApiModel用于描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用 @ApiImplicitParam注解进行描述的时候 @ApiModelProperty用来描述一个Model的属性。
属性值：
ApiModel
| 属性 | 描述 |
|---|---|
| value | 提供一个供选择的名称，默认为类名 |
| description | 对类的描述 |
| parent | 为模型提供一个超类以允许描述继承 |
| discriminator | 支持继承和多态，作为一个字段标识浮，以便于子类继承使用 |
| subTypes | 从这个模型继承的子类型的数组 |
| reference | 指定对相应类型定义的引用，覆盖指定的任何其他元数据 |
ApiModelProperty
| 属性 | 描述 |
|---|---|
| value | A brief description of this property. |
| name | Allows overriding the name of the property |
| allowablevalues | 限制参数可接受的值 |
| access | Allows for filtering a property from the API documentation. See io.swagger.core.filter.SwaggerSpecFilter. |
| notes | 标签描述，1.5已经没实际作用 |
| datatype | 指定数据类型 可以是一个类或者原始类型 |
| request | true/false 是否必填 |
| position | 属性位置排序 默认0 |
| hidden | 是否展现 true/false 默认false |
| example | 属性值的 参考数据 |
| readOnly | 是否只读 ture/false |
| accessMode | 允许指定模型的访问模式 枚举为本类(AccessMode.READ_ONLY, READ_WRITE) |
| reference | 指定对相应类型定义的引用，覆盖指定的任何其他元数据 |
| allowEmptyValue | 是否允许空值输入 默认false |
| extensions | 扩展属性 |
实例：
@ApiModel(value = "user",description = "用户相关入参")
public class UserParam {@ApiModelProperty(name="userName" , value = "用户名称",dataType ="java.lang.String",position = 1,example = "tab")private String userName;@ApiModelProperty(name="password" , value = "用户密码",dataType ="java.lang.String",position = 2,example = "123",required = true,allowableValues = "1,2,3")private String password;
7、 @PathVariable
描述：@PathVariable用于获取get请求url路径上的参数，即参数绑定的作用，通俗的说是url中"?"前面绑定的参数。
属性值：
| 属性 | 描述 |
|---|---|
| value | 属性Key |
| name | 同上 |
| required | 是否必填，默认必须 |
参考：使用率比较高 但是功能表单一
@GetMapping(value = "/{user}")
public void test(@PathVariable("user") String user){System.out.println( "Hello "+ user);
}
8、 @RequestParam
描述：@RequestParam用于获取前端传过来的参数，可以是get、post请求，通俗的说是url中"?"后面拼接的每个参数。
属性值：
| 属性 | 描述 |
|---|---|
| value | 属性Key |
| name | 同上 |
| required | 是否必填，默认必须 |
| defaultValue | 默认值 |
参考： 上述demo
三、Swagger引入
springfox-swagger-ui依赖并不是必须的，可以使用第三方的UI，也可以自己写一套前端的UI集成进来。
我们就可以使用一个基于bootstrap写的UI。
1、引入依赖
1) 默认swagger
<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.9.2</version>
</dependency>
2) bootstrap
<dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-spring-boot-starter</artifactId><version>2.0.2</version>
</dependency>
1)默认的swagger界面： http://localhost:8080/swagger-ui
引入第三方Bootstrap编写的UI：http://localhost:8080/doc.html#/home
2、基本配置
参考代码 以当bootstrap为例
package com.fewin.config;import com.google.common.base.Predicates;
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.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;import java.util.regex.Pattern;/*** @Author : xuwl* @Date : Created on 上午10:04 2021/3/11* @Package Name : com.fewin.com.fewin.config* @Des : Swagger配置* @Version: v0.1*/
@Configuration
@EnableSwagger2
public class SwaggerConfig {@Value("${swagger.enable}")private boolean enable;private ApiInfo setApiInfo(String title, String version, String desc, Contact contact) {return new ApiInfoBuilder().title(title).description(desc).contact(contact).version(version).build();}@Beanpublic Docket setSWaggerDocket() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(setApiInfo("01sbd", "V0.1", "简单的swagger配置", new Contact("xuwl", "www.baidu.com", "tab_xu@123.com"))).enable(enable).select().paths(Predicates.not(PathSelectors.regex("/error.*")))//过滤所有的错误标签接口.paths(PathSelectors.ant("/swagger/**")).build().groupName("Swagger Paths");}@Beanpublic Docket setBaseDocket() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(setApiInfo("01sbd", "V0.1", "简单的swagger配置", new Contact("xuwl", "www.baidu.com", "tab_xu@123.com"))).enable(enable).select().paths(PathSelectors.ant("/common/**")).build().groupName("Common Paths");}@Beanpublic Docket setSpecialDocket() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(setApiInfo("01sbd", "V0.1", "简单的swagger配置", new Contact("xuwl", "www.baidu.com", "tab_xu@123.com"))).enable(enable).select().paths(Predicates.not(PathSelectors.regex("/error.*")))//过滤所有的错误标签接口.paths(PathSelectors.ant("/test/**")).build().groupName("Special Paths");//.pathMapping("/test/"); //添加请求权限，进行所有请求的权限增加}
}
Swagger 01 入门相关推荐
- javaSE学习笔记01 入门篇
javaSE学习笔记01 入门篇 java语言概述 Java背景知识 java是 美国 sun 公司 在1995年推出的一门计算机高级编程语言. java早期称为Oak(橡树),后期改名为Java. ...
- swagger快速入门(springfox)
swagger快速入门 什么是swagger 什么是springfox 什么是swagger-bootstrap-ui 使用方法 第一步 第二步 第三步 完整代码 特别注意 什么是swagger sw ...
- 【ECharts系列|01入门】 从入门到天黑【入门级教程实战】
ECharts 是一个使用 JavaScript 实现的开源可视化库,涵盖各行业图表,满足各种需求. ECharts 遵循 Apache-2.0 开源协议,免费商用. ECharts 兼容当前绝大部分 ...
- VMTK学习——01.入门
写在这里的初衷,一是备忘,二是希望得到高人指点,三是希望能遇到志同道合的朋友. 目录 入门 读取和显示图像 关于文件名的注释 图像格式转换 档案格式 感兴趣体积(VOI)提取 使用Marching C ...
- 从0-1入门python爬虫，看这篇就够了！
看到很多大牛在回答像"如何入门爬虫"这种问题的时候,一如当年学霸讲解题目,跳步无数,然后留下一句"不就是这样推嘛",让一众小白菜鸟一脸懵逼..作为一个0起步(之 ...
- [转载]微信公众号开发 [01] 入门基本流程
1.公众号的类别和注册 1.1 公众号类别 微信公众号目前有三种,订阅号.服务号.企业号,另外还有一种后来推出的和公众号带点关系的小程序. 订阅号.服务号和企业号的功能区别如下(更多详细区别戳参考链 ...
- 深度学习01——入门基础 基于Python
目录 1.知道什么是深度学习 2.机器学习和深度学习的区别 3.深度学习的应用场景 4.常见的深度学习框架 5.为什么要学习Pytorch框架 5.神经网络的介绍: 1).概念: 2).神经元 3). ...
- 老宇哥带你玩转ESP32：01入门介绍
接触物联网差不多10年了. 先跟大家聊聊,老宇哥11年进入大学,大一就在实验室开始了电子研发,记得那时候师兄介绍我买了一块郭天祥老师的51开发板,还有配套的一本书,虽然从小非常喜欢电子,经常折腾,有一 ...
- MyBatis-Plus 01入门
参考网站 官网:http://mp.baomidou.com 参考教程:http://mp.baomidou.com/guide/ 一.简介 MyBatis-Plus(简称 MP)是一个 MyBati ...
最新文章
- C# - linq查询现有的DataTable
- Java5线程并发库之LOCK（锁）CONDITION（条件）实现线程同步通信
- windows获取IP和MAC地址【Qt】
- 用python画玫瑰花脚本-python画一个玫瑰和一个爱心
- 【供应链案例】解密可口可乐供应链管理策略，揭头部饮料企业成功之道
- 【微积分的本质|笔记】指数函数求导
- Docker容器访问外部世界
- QPS、TPS、吞吐量含义
- cesium添加填充_cesium实现注记功能
- Win7系统下安装微磁学软件OOMMF方法
- 用python画简单雪花剪纸步骤图解_Python+Selenium+Beautiful Soap抓取贝贝拼团爆款
- Docker常用容器命令
- win10照片打印闪退
- SIP软交换相关介绍
- 在openlayer中对瓦片地图进行平移
- MCE公司：新型靶向RAS突变的共价抑制剂
- 百度云 x 中国联通 | 立标杆，中国联通新客服上线大幕拉开！
- rman备份(教程与案例)
- 计算机研究生就业方向之去银行券商信息技术部门
- git从gitHub下载代码