[转]swagger2 入门教程
swagger2 是一个规范和完整的框架,用于生成、描述、调用和可视化Restful风格的web服务,现在我们使用spring boot 整合它
作用:
1、接口的文档在线自动生成
2、功能测试
先介绍它的常用注解
@Api 注解可以用来标记 Controller 的功能
@ApiOperation 注解用来标记一个方法的作用
@ApilmplicitParam 注解用来描述一个参数,可以配置参数的中文含义,也可以给参数设置默认值,这样在接口测试的时候可以避免手动输入
@ApilmplicitParams 如果有多个参数,则需要使用多个 @ApilmplicitParam 注解来描述, 多个 @ApilmplicitParam 注解需要放在一个 @ApilmplicitParams 注解中
@ApiModel 如果参数是一个对象,则需要在对象所在的类上加上此注解
@ApiModelProperty 如果参数是一个对象,则需要在对应的属性上加上此注解,还需要在对象所在的类上加上 @ApiModel
@ApiIgnore 注解标识此参数可以忽略
下面介绍它的使用
1、引入它的依赖
<!--写接口文档的api-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>${swagger.version}</version>
<exclusions>
<exclusion>
<artifactId>guava</artifactId>
<groupId>com.google.guava</groupId>
</exclusion>
</exclusions>
</dependency>
<dependency>
<groupId>com.google.guava</groupId>
<artifactId>guava</artifactId>
<version>${guava.version}</version>
</dependency>
<!--界面支持-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>${swagger.version}</version>
</dependency>
2、使用开启注解 @EnableSwagger2 和 配置映射路径、要扫描的接口的未知、文档网站信息
package io.xiongdi.config; import io.swagger.annotations.ApiOperation;
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.service.ApiKey;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2; import java.util.ArrayList;
import java.util.List; /**
* @author wujiaxing
* <p>
* 使用Swagger2只需三步
* 1、导入Swaggerr依赖
* 2、配置Docket的bean
* 3、使用@Api等注解修饰
* </p>
*/
@Configuration
@EnableSwagger2
public class SwaggerConfig { @Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
// 方法需要有ApiOperation注解才能生存接口文档
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
// 路径使用any风格
.paths(PathSelectors.any())
.build()
// 如何保护我们的Api,有三种验证(ApiKey, BasicAuth, OAuth)
.securitySchemes(security())
// 接口文档的基本信息
.apiInfo(apiInfo());
} /**
* 接口文档详细信息
*
* @return
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder().title("兄弟足浴").description("xd-api文档").termsOfServiceUrl("http://www.localhost:8002").version("1.0.0").build();
} private List<ApiKey> security() {
ArrayList<ApiKey> apiKeys = new ArrayList<>();
apiKeys.add(new ApiKey("token", "token", "header"));
return apiKeys;
}
}
3、使用它的注解标识要创建的接口文档
package io.xiongdi.controller; import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.xiongdi.annotation.Login;
import io.xiongdi.common.utils.R;
import io.xiongdi.common.validator.ValidatorUtils;
import io.xiongdi.form.LoginForm;
import io.xiongdi.service.TokenService;
import io.xiongdi.service.UserService;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;
import springfox.documentation.annotations.ApiIgnore; import java.util.Map; /**
* @author wujiaxing
* @date 2019-07-07
*/
@Api(tags = "登录接口")
@RequestMapping("/api")
@RestController
public class ApiLoginController { @Autowired
private TokenService tokenService;
@Autowired
private UserService userService; @RequestMapping("login")
@ApiOperation("登录")
public R login(@RequestBody LoginForm loginForm) {
// 服务端表单校验
System.out.println("已进入login"+loginForm);
ValidatorUtils.validateEntity(loginForm);
// 执行登录
Map<String, Object> map = userService.login(loginForm); return R.ok(map);
} /**
* <p>
* 登出需要请求中带token
* @RequestAttribute 这个注解表示访问有过滤器或拦截器创建的、预先存在的属性
* </p>
* @param userId
* @return
*/
@Login
@ApiOperation("登出")
@RequestMapping("logout")
public R logout(@RequestAttribute("userId") @ApiIgnore long userId) {
tokenService.expireToken(userId);
return R.ok();
}
}
package io.xiongdi.form; import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data; import javax.validation.constraints.NotBlank; /**
* 登录表单
* @author wujiaxing
* @date 2019-06-30
*/
@Data
@ApiModel(value = "登录表单")
public class LoginForm { @ApiModelProperty(value = "手机号")
@NotBlank(message = "手机号不能为空")
private String mobile; @ApiModelProperty(value = "密码")
@NotBlank(message = "密码不能为空")
private String password;
}
4、正常来说,配置以上三步就可以了,但如果配置了跨域,则需要配置静态资源放过
package io.xiongdi.config; import io.xiongdi.interceptor.AuthorizationInterceptor;
import io.xiongdi.resolver.LoginUserHandlerMethodArgumentResolver;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.method.support.HandlerMethodArgumentResolver;
import org.springframework.web.servlet.config.annotation.CorsRegistry;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer; import java.util.List; /**
* @author wujiaxing
* <p>
* 此配置类可配置拦截器、参数解析器、返回值解析器、跨域支持等等
* </p>
*/
@Configuration
public class WebMvcConfig implements WebMvcConfigurer { @Autowired
private AuthorizationInterceptor authorizationInterceptor;
@Autowired
private LoginUserHandlerMethodArgumentResolver loginUserHandlerMethodArgumentResolver; /**
* 如果配置跨域,就增加这个配置
* @param registry
*/
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("/static/**").addResourceLocations("/static/");
registry.addResourceHandler("/js/**").addResourceLocations("/js/");
registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars");
} /**
* 拦截器配置
* @param registry
*/
@Override
public void addInterceptors(InterceptorRegistry registry) {
registry.addInterceptor(authorizationInterceptor).addPathPatterns("/api/**");
} /**
* 跨域支持配置
* @param registry
*/
@Override
public void addCorsMappings(CorsRegistry registry) {
registry.addMapping("/**").allowCredentials(true).allowedOrigins("*").allowedMethods("GET", "PUT", "DELETE", "POST", "OPTIONS").maxAge(3600);
} /**
* 参数解析配置
* @param resolvers
*/
@Override
public void addArgumentResolvers(List<HandlerMethodArgumentResolver> resolvers) {
resolvers.add(loginUserHandlerMethodArgumentResolver);
}
}
至此基本配置已完成,访问 localhost:8080/swagger-ui.html
---------------------
作者:过儿写代码也在想姑姑
来源:CNBLOGS
原文:https://www.cnblogs.com/wujiaxing/p/11180361.html
版权声明:本文为作者原创文章,转载请附上博文链接!
内容解析By:CSDN,CNBLOG博客文章一键转载插件
[转]swagger2 入门教程的更多相关文章
- Spring Boot2 快速入门教程-到上手
Spring Boot2 教程合集 入门 纯 Java 代码搭建 SSM 环境 创建一个 Spring Boot 项目的三种方法 理解 Spring Boot 项目中的 parent 基础配置 配置文 ...
- wepack+sass+vue 入门教程(三)
十一.安装sass文件转换为css需要的相关依赖包 npm install --save-dev sass-loader style-loader css-loader loader的作用是辅助web ...
- wepack+sass+vue 入门教程(二)
六.新建webpack配置文件 webpack.config.js 文件整体框架内容如下,后续会详细说明每个配置项的配置 webpack.config.js直接放在项目demo目录下 module.e ...
- wepack+sass+vue 入门教程(一)
一.安装node.js node.js是基础,必须先安装.而且最新版的node.js,已经集成了npm. 下载地址 node安装,一路按默认即可. 二.全局安装webpack npm install ...
- Content Security Policy 入门教程
阮一峰文章:Content Security Policy 入门教程
- gulp详细入门教程
本文链接:http://www.ydcss.com/archives/18 gulp详细入门教程 简介: gulp是前端开发过程中对代码进行构建的工具,是自动化项目的构建利器:她不仅能对网站资源进行优 ...
- UE4新手引导入门教程
请大家去这个地址下载:file:///D:/UE4%20Doc/虚幻4新手引导入门教程.pdf
- ABP(现代ASP.NET样板开发框架)系列之2、ABP入门教程
点这里进入ABP系列文章总目录 基于DDD的现代ASP.NET开发框架--ABP系列之2.ABP入门教程 ABP是“ASP.NET Boilerplate Project (ASP.NET样板项目)” ...
- webpack入门教程之初识loader(二)
上一节我们学习了webpack的安装和编译,这一节我们来一起学习webpack的加载器和配置文件. 要想让网页看起来绚丽多彩,那么css就是必不可少的一份子.如果想要在应用中增加一个css文件,那么w ...
随机推荐
- Spring Boot → 11:项目实战-账单管理系统完整版
Spring Boot → 11:项目实战-账单管理系统完整版
- TyvjP1266 费解的开关
P1266 费解的开关 时间: 1000ms / 空间: 131072KiB / Java类名: Main 描述 你玩过“拉灯”游戏吗?25盏灯排成一个5x5的方形.每一个灯都有一个开关,游戏 ...
- 洛谷 P1948 [USACO08JAN]电话线Telephone Lines 最短路+二分答案
目录 题面 题目链接 题目描述 输入输出格式 输入格式 输出格式 输入输出样例 输入样例 输出样例 说明 思路 AC代码 题面 题目链接 P1948 [USACO08JAN]电话线Telephone ...
- PHP核心编程-图像操作
一 图像操作环境: 1. 开启GD2图像处理并检测 在php.ini开启GD库 2. 画布坐标系说明 二. 图像基本操作(步骤) 1. 创建图像 创建画布(图像资源) 创建的方法: ...
- JS设计模式之单例模式(一)
单例就是保证一个类只有一个实例,实现的方法一般是先判断实例存在与否,如果存在直接返回,如果不存在就创建了再返回,这 就确保了一个类只有一个实例对象. 在JavaScript里,实现单例的方式有很多种, ...
- HTML-DOM实例——实现带样式的表单验证
HTML样式 基于table标签来实现页面结构 <form id="form1"> <h2>增加管理员</h2> <table&g ...
- 【转载】【python】python练手项目
入门篇 1.Python - Python 图片转字符画 50 行 Python 代码完成图片转字符画小工具. <img src="https://pic3.zhimg.com ...
- 遗传算法MATLAB实现(1):工具箱下载及安装
到官网下载谢菲尔德大学的GA工具箱:http://codem.group.shef.ac.uk/index.php/ga-toolbox(其实蛮不懂为什么有人把这个传到某个网上还需要积分才能下载,人家 ...
- Effective Modern C++:01类型推导
C++的官方钦定版本,都是以ISO标准被接受的年份命名,分别是C++98,C++03,C++11,C++14,C++17,C++20等.C++11及其后续版本统称为Modern C++. C++11之 ...
- hdu4310 贪心
考虑每次血口的要少 就按照一滴血多少伤害来计算.由于直接相除有小数.考虑x/y > a/b => x*b >y*a; #include<stdio.h> #inclu ...