swagger2的简单使用

优点:

可以生成文档形式的API并提供给不同的团队使用

便于自己单测

无需过多冗余的word文档,这一点很重要,因为我在工作中就遇到这么一个情况,由于开发使用的文档和最新文档版本导致不一致,导致后期很烦人

=使用swagger流程=

1.引入pom依赖

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

2.新建swagger2配置类

new class Swagger2

@Configuration //使用配置类注解
@EnableSwagger2 //启用这个配置类
public class Swagger2 {
/**
* @Description:swagger2的配置文件,这里可以配置swagger2的一些基本的内容,比如扫描的包等等
*/
@Bean //配置这个bean是为了让swagger扫描到controller
public Docket createRestApi() { // 为swagger添加header参数可供输入
// ParameterBuilder userTokenHeader = new ParameterBuilder();
// ParameterBuilder userIdHeader = new ParameterBuilder();
// List<Parameter> pars = new ArrayList<Parameter>();
// userTokenHeader.name("headerUserToken").description("userToken")
// .modelRef(new ModelRef("string")).parameterType("header")
// .required(false).build();
// userIdHeader.name("headerUserId").description("userId")
// .modelRef(new ModelRef("string")).parameterType("header")
// .required(false).build();
// pars.add(userTokenHeader.build());
// pars.add(userIdHeader.build()); return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
.apis(RequestHandlerSelectors.basePackage("com.csylh.controller"))
.paths(PathSelectors.any()).build();
// .globalOperationParameters(pars);
} /**
* @Description: 构建 api文档的信息
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
// 设置页面标题
.title("swagger2构建接口数据文档,这里是文档的标题")
// 设置联系人
.contact(new Contact("留歌", "http://csylh.cn", "csylh36@163.com"))
// 描述
.description("留歌短视频,这里是描述信息")
// 定义版本号
.version("V-1.0").build();
} }

3.配置controller类,方法和实体类

3.1对于某一个Controller添加一个API====@Api

@Api:用在请求的类上,表示对类的说明

- tags="说明该类的作用,可以在UI界面上看到的注解"

- value="该参数没什么意义,在UI界面上也看到,所以不需要配置"

案例:

@Api(value = "用户注册登录接口",tags = {"登录注册注销的controller"})

public class UserController{}

3.2对于Controller不同的接口(方法)进行定义==@ApiOperation

@ApiOperation:用在请求的方法上,说明方法的用途、作用

- value="说明方法的用途、作用"

- notes="方法的备注说明"

案例:

@ApiOperation(value = "用户注册接口", notes="这是用户注册的接口,随便写都可以")

public ServerResponse register(@RequestBody Users user){

return iUserService.register(user);

}

接下来对方法参数情况进行分类

情况一:(String userId,String fanId)参数场景

方法参数的问题:上面的是@RequestBody这样的场景,有的时候就是一个个参数 (String userId,String fanId)

我们就可以使用@ApiImplicitParams来定义参数

@ApiImplicitParams:用在请求的方法上,表示一组参数说明

- @ApiImplicitParam:用在@ApiImplicitParams注解中,指定一个请求参数的各个方面

- name:参数名

- value:参数的汉字说明、解释

- required:参数是否必须传

- paramType:参数放在哪个地方

header --> 请求参数的获取:@RequestHeader

query --> 请求参数的获取:@RequestParam

path(用于restful接口)--> 请求参数的获取:@PathVariable

body(不常用)

form(不常用)

- dataType:参数类型,默认String,其它值dataType="Integer"

- defaultValue:参数的默认值

案例:

@ApiOperation(value="用户头像上传", notes="用户头像上传接口")

@ApiImplicitParam(name="userId", value="用户id", required=true,

dataType="String", paramType="query")

public ServerResponse uploadIcon(String userId,@RequestParam("file") MultipartFile[] files) throws IOException {

return iUserService.uploadIcon(userId,files);

}

情况二:参数是使用@RequestBody这样的场景

上面这样基本配置之后其实也是可以进行运行的,但是我们更好的是可以对传入的users参数做一些限制,例如,传入的username参数字段不能为空等

操作: 跟进Users这个实体类进行配置

因为Users是一个实体,所以就要定义为@ApiModel

@ApiModel:用于响应类上,表示一个返回响应数据的信息

这种一般用在post创建的时候,使用@RequestBody这样的场景

请求参数无法使用@ApiImplicitParam注解进行描述的时候)

案例:

@ApiModel(value = "用户对象,这里是解释",description = "这是用户对象,这里是描述")

public class Users {}

实体类上字段的处理

=前端必须传入过来的字段情况=@ApiModelProperty

//用户名字段
@ApiModelProperty(value = "用户名",name = "username",example = "liuge36",required = true)
private String username;
//前端传过来的密码字段
@ApiModelProperty(value = "密码",name = "password",example = "123456",required = true)
private String password;

====前端不需要传入过来的字段情况,不需要显示 @ApiModelProperty(hidden = true)

@ApiModelProperty(hidden = true)

private String id;

这样就不会显示出来了

===到这里,基本的使用就到位了,后期有机会跟新更多swagger2的用法

补充:定义包扫描

@MapperScan(basePackages="com.csylh.mapper")

swagger2的简单使用的更多相关文章

  1. 十、Spring boot 简单优雅的整合 Swagger2

    前言 swagger2 是什么,我这里就不说了,就是一个简单的接口文档,方便前后端联调. 其实之前没有想要到要使用swagger 的.因为我之前用的是YAPI ,不过这个是一个单独的工具.并且是开源的 ...

  2. Spring Boot 2.x (十二):Swagger2的正确玩儿法

    Swagger2简介 简单的来说,Swagger2的诞生就是为了解决前后端开发人员进行交流的时候API文档难以维护的痛点,它可以和我们的Java程序完美的结合在一起,并且可以与我们的另一开发利器Spr ...

  3. Spring Boot 集成 Swagger2 与配置 OAuth2.0 授权

    Spring Boot 集成 Swagger2 很简单,由于接口采用了OAuth2.0 & JWT 协议做了安全验证,使用过程中也遇到了很多小的问题,多次尝试下述配置可以正常使用. Maven ...

  4. 整合swagger2生成Restful Api接口文档

    整合swagger2生成Restful Api接口文档 swagger Restful文档生成工具 2017-9-30 官方地址:https://swagger.io/docs/specificati ...

  5. 谈谈Java常用类库中的设计模式 - Part Ⅰ

    背景 最近一口气看完了Joshua Bloch大神的Effective Java(下文简称EJ).书中以tips的形式罗列了Java开发中的最佳实践,每个tip都将其意图和要点压缩在了标题里,这种做法 ...

  6. Spring的学习与实战

    目录 一.Spring起步 学习路线图 Spring的基础知识 什么是Spring Spring框架核心模块 SpringBoot 第一个Spring应用DEMO 编写自己的第一个SpringMVC例 ...

  7. 【分布式】-- 基于Nacos、OpenFeign搭建的微服务抽奖系统后台小案例

    1.项目介绍 最近入项目之前要求熟悉一下SpringCloud Nacos微服务基于Feign接口调用并整合Swagger2进行接口文档展示给前端,所以自己按照要求来编写并整合了一套基于SpringC ...

  8. swagger2简单使用

    1.引入jar <!--引入swagger--> <dependency> <groupId>io.springfox</groupId> <ar ...

  9. Swagger2简单使用教程

    Swagger2简单使用教程 1.简介 ​ Swagger是为了解决企业中接口(api)中定义统一标准规范的文档生成工具.很多采用前后端分离的模式,前端只负责调用接口,进行渲染,前端和后端的唯一联系, ...

随机推荐

  1. Java IO体系之RandomAccessFile浅析

    Java IO体系之RandomAccessFile浅析 一.RandomAccessFile综述: 1.1RandomAccessFile简介 RandomAccessFile是java Io体系中 ...

  2. C#开发BIMFACE系列14 服务端API之批量获取转换状态详情

    系列目录     [已更新最新开发文章,点击查看详细] 上一篇<C#开发BIMFACE系列13 服务端API之获取转换状态>中介绍了根据文件ID查询单个文件的转换状态. 本文介绍批量获取转 ...

  3. IDEA 中用好 Lombok,撸码效率至少提升5倍!

    来 源:http://t.cn/EXhxRzV 以前的Java项目中,充斥着太多不友好的代码:POJO的getter/setter/toString:异常处理:I/O流的关闭操作等等,这些样板代码既没 ...

  4. 设置普通用户输入sudo,免密进入root账户

    满足给开发用户开权限,赋予sudo权限.又不让其输入密码的方式: 方式一: 开始系统内部的wheel用户组, 在/etc/suoers 中编辑配置文件如下: %wheel ALL=(ALL) NOPA ...

  5. 那些年,我们误解的 JavaScript 闭包

    说到闭包,大部分的初始者,都是谈虎色变的.最近对闭包,有了自己的理解,就感觉.其实我们误解闭包.也被网上各种说的闭包的解释给搞迷糊. 一句话:要想理解一个东西还是看权威的东西. 下面我来通俗的讲解一个 ...

  6. mysql之innodb存储引擎---数据存储结构

    一.背景 1.1文件组织架构 首先看一下mysql数据系统涉及到的文件组织架构,如下图所示: msyql文件组织架构图 从图看出: 1.日志文件:slow.log(慢日志),error.log(错误日 ...

  7. 时间复杂度big-O、Big-Omega和big-Theta

    我们有三种曲线:   A curve that we know is "above" the running time function when n is large. ( Bi ...

  8. java.util.Timer简介

    Timer是用于管理在后台执行的延迟任务或周期性任务,其中的任务使用java.util.TimerTask表示.任务的执行方式有两种: 按固定速率执行:即scheduleAtFixedRate的两个重 ...

  9. 基础知识:什么是SNMP

    简单网络管理协议(SNMP) 是专门设计用于在 IP 网络管理网络节点(服务器.工作站.路由器.交换机及HUBS等)的一种标准协议,它是一种应用层协议. SNMP 使网络管理员能够管理网络效能,发现并 ...

  10. Redis集群增加节点和删除节点

    本文主要是承接上一篇文章Redis集群的离线安装成功以后,我们如何进行给集群增加新的主从节点(集群扩容)以及如何从集群中删除节点(集群缩容),也就是集群的伸缩,集群伸缩的原理是控制虚拟槽和数据在节点之 ...