Swagger2

Swagger2 整合 Springboot

地址：https://blog.csdn.net/simba1949/article/details/80919183

什么是swagger2

编写和维护接口文档是每个程序员的职责，根据 Swagger2 可以快速帮助我们编写最新的API接口文档，再也不用担心开会前仍忙于整理各种资料了，间接提升了团队开发的沟通效率。常用注解swagger通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等。

Swagger2 配置类

代码

package top.simba1949.config;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* @author simba@onlying.cn* @date 2018/7/4 21:36*/
@Configuration
@EnableSwagger2
public class Swagger2 {/*** swagger2 启动后，通过createRestApi函数创建Docket的Bean，* apiInfo() 用来创建该Api的基本信息（这些基本信息会展现在文档页面中）。* select() 函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现，* 本例采用指定扫描的包路径来定义，Swagger会扫描该包下所有Controller定义的API，并产生文档内容（除了被@ApiIgnore指定的请求）。* @return*/@Beanpublic Docket createRestApi() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.basePackage("top.simba1949.controller")).paths(PathSelectors.any()).build();}private ApiInfo apiInfo() {return new ApiInfoBuilder().title("Spring Boot中使用Swagger2构建RESTful APIs").description("springboot学习笔记").termsOfServiceUrl("http://localhost:8080/").version("1.0").build();}}

效果

常用注解

@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述
@ApiModel：用对象来接收参数
@ApiModelProperty：用对象接收参数时，描述对象的一个字段
@ApiIgnore：使用该注解忽略这个API，用于类或者方法上
@ApiImplicitParam：一个请求参数，用于方法上

@ApiImplicitParams：多个请求参数，包含多个 @ApiImplicitParam，用于方法上

@Api：用在请求的类上，表示对类的说明tags="说明该类的作用，可以在UI界面上看到的注解，如果tags多个值，会生成多个list"value="该参数没什么意义，在UI界面上也看不到，所以不需要配置"@ApiOperation：用在请求的方法上，说明方法的用途、作用value="说明方法的用途、作用"notes="方法的备注说明"@ApiParam：单个参数描述- name：参数名- value：参数说明- required：是否必填@ApiModel：用对象来接收参数- value：表示对象名- description：对对象的描述
@ApiModelProperty：用对象接收参数时，描述对象的一个字段- value：字段说明- name：重写属性名- dataType：重写属性类型- example：举例说明- hidden：隐藏@ApiIgnore：使用该注解忽略这个API，用于类或者方法上@ApiImplicitParams：用在请求的方法上，表示一组参数说明@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面name：参数名value：参数的汉字说明、解释required：参数是否必须传paramType：参数放在哪个地方· header --> 请求参数的获取：@RequestHeader· query --> 请求参数的获取：@RequestParam· path（用于restful接口）--> 请求参数的获取：@PathVariable· body（不常用）· form（不常用）    dataType：参数类型，默认String，其它值dataType="Integer"       defaultValue：参数的默认值

@Api：

修饰整个类，描述Controller的作用

@Api
- tags：对类的说明

代码

/*** @Api * value="不会再界面显示出来"* tags="说明该类的作用，可以在UI界面上看到的注解，如果tags多个值，会生成多个list"* @date 2018/7/4 20:17*/
@Api(tags = {"用户操作接口"})
@Controller
@RequestMapping("/user")
public class UserController {}

效果

@ApiOperation:

描述一个类的一个方法，或者说一个接口

@ApiOperation
- value：用于方法描述
- notes：用于提示内容

代码

@ApiOperation(value = "用于方法描述",notes = "用于提示内容")
@GetMapping("/{data}")
@ResponseBody
public ResponseCommon string(@PathVariable String data){return ResponseBuilder.buildSuccessResponse(data);
}

效果

@ApiParam：

用于单个参数描述

@ApiParam
- name：参数名
- value：参数说明
- required：是否必填

代码

@ApiOperation(value = "用于方法描述",notes = "用于提示内容")
@GetMapping("/{data}")
@ResponseBody
public ResponseCommon string(@ApiParam(name = "data",value = "参数说明",required = true)@PathVariable String data){return ResponseBuilder.buildSuccessResponse(data);
}

效果

@ApiModel & @ApiModelProperty

@ApiModel：用对象来接收参数

@ApiModelProperty：用对象接收参数时，描述对象的一个字段

@ApiModel：用对象来接收参数
- value：表示对象名
- description：对对象的描述
@ApiModelProperty：用对象接收参数时，描述对象的一个字段
- value：字段说明
- name：重写属性名
- dataType：重写属性类型
- example：举例说明
- hidden：隐藏

代码

package top.simba1949.common;import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;/*** @author simba@onlying.cn* @date 2018/7/4 20:18*/
@ApiModel(value = "用户的POJO",description = "对对象的描述")
public class UserCommon {@ApiModelProperty(value = "用户Id",name = "userId",dataType = "int",required = true,example = "1",hidden = true)private int userId;@ApiModelProperty(value = "用户名",name = "username",dataType = "String",required = true,example = "李白")private String username;@ApiModelProperty(value = "用户年龄",name = "age",dataType = "int",required = true,example = "888")private int age;@ApiModelProperty(value = "用户密码",name = "password",dataType = "String",required = true,example = "19491001")private String password;// getter/setter方法省略
}

效果

@ApiIgnore：

使用该注解忽略这个API，用于类或者方法上

@ApiImplicitParams & @ApiImplicitParam

@ApiImplicitParams ：多个请求参数，用于方法上，包含多个 @ApiImplicitParam

@ApiImplicitParam：一个请求参数，用于方法上

@ApiImplicitParam
- name：参数名
- value：参数说明
- dataType：参数类型，默认String，其他值dataType=“Integer”
- paramType：参数发在哪个地方
  - header：请求参数的获取 @RequestHeader
  - query：请求参数的获取 @RequestParam
  - path：请求参数的获取 @PathVariable
  - body（不常用）
  - form （不常用）
- required：是否必须填写
- defaultValue：默认值

代码

@ApiOperation(value = "用于方法描述query",notes = "这是用来说明该方法，提示内容")
@ApiImplicitParams({@ApiImplicitParam(name = "data",value = "字符串数据",dataType = "String",paramType = "path",example = "白居易",required = true,defaultValue = "白居易"),@ApiImplicitParam(name = "i",value = "int类型",dataType = "int",paramType = "path",example = "666",required = true,defaultValue = "666")
})
@PostMapping("/query/{data}/{i}")
@ResponseBody
public ResponseCommon query(@PathVariable String data,@PathVariable int i){return ResponseBuilder.buildSuccessResponse(data + i);
}

效果

Swagger2学习笔记相关推荐

SpringBoot学习笔记(16)----SpringBoot整合Swagger2
Swagger 是一个规范和完整的框架,用于生成,描述,调用和可视化RESTful风格的web服务 http://swagger.io Springfox的前身是swagger-springmvc,是 ...
MyBatis-Plus 学习笔记
MyBatis-Plus 学习笔记学习官网: https://mp.baomidou.com/guide/ 一.快速入门 1.简介 MyBatis的增强工具,在Mybatis的基础上只做增强功能,兼 ...
Rabbitmq学习笔记(尚硅谷2021)
Rabbitmq学习笔记 (尚硅谷) 1.MQ 的概念 1.1 什么是 MQ? 1.2 为什么要用 MQ? 削峰解耦异步 1.3 MQ 的分类 ActiveMQ Kafka RocketMQ Ra ...
尚硅谷谷粒学院学习笔记（防坑点的总结部分勘误）
谷粒学院学习笔记部分勘误数据库设计规约模块说明环境搭建创建一个Spring Boot 的父工程,版本使用:2.2.1.RELEASE 父工程pom.xml里面添加在pom.xml中添加依赖 ...
SpringBoot(学习笔记)
SpringBoot学习笔记从今天开始就进入微服务阶段一些小问题 1.HelloWorld 1.1回顾什么是Spring 1.2什么是SpringBoot 1.3微服务架构 2.第一个Spring ...
尚医通项目学习笔记Part1
尚医通项目学习笔记前言一.目前学习进度二.学习记录 1.项目简介 1.1 项目所会用到的技术栈 1.2 业务流程 2.项目学习笔记 2.1MyBatis-Plus相关 2.2搭建项目框架 2.3 ...
Docker 学习笔记 - 进阶四 Docker网络和 Docker compose
Docker 学习笔记 - 进阶四 Docker网络和 Docker compose 4. docker 网络 4.1 docker network是什么 4.1.1 docker不启动,默认网络情况 ...
SpringBoot 学习笔记
SpringBoot 学习笔记文章目录 SpringBoot 学习笔记 1. SpringBoot简介 1.1 什么是Spring 1.2 Spring 是如何简化Java开发的 1.3 什么是 S ...
Rabbitmq学习笔记教程-尚硅谷
Rabbitmq学习笔记 (尚硅谷) 尚硅谷 rabbitmq 教程 1.MQ 的概念 1.1 什么是 MQ? 存放消息的队列,互联网架构中常见的一种服务与服务之间通信的方式. 1.2 为什么要用 M ...

Swagger2学习笔记

Swagger2

Swagger2 整合 Springboot

什么是swagger2

Swagger2 配置类

代码

效果

常用注解

@Api：

代码

效果

@ApiOperation:

代码

效果

@ApiParam：

代码

效果

@ApiModel & @ApiModelProperty

代码

效果

@ApiIgnore：

@ApiImplicitParams & @ApiImplicitParam

代码

效果

Swagger2学习笔记相关推荐

最新文章

热门文章