[转]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 ...
随机推荐
- vue学习之组件(component)(二)
自定义事件 父组件使用 prop 传递数据给子组件.但子组件怎么跟父组件通信呢?这个时候 Vue 的自定义事件系统就派得上用场了. 1. 使用 v-on 绑定自定义事件 每个vue实例都实现了事件接口 ...
- 如何把pdf文档转化为word
在工作中常常遇到大量的pdf文档,再加工进行处理文件,特别的不方便,需要转换为WORD. 尝试如下: 使用wps自带的工具转换,提示需要是会员才能进行.否则只能进行5页以下的转换. 再想是不是又有个这 ...
- Ubuntu 12.04 安装 IQQ
1. 安装 IQQ 首先应安装jdk包 2. 百度网盘下载: http://pan.baidu.com/share/home?uk=3071047022 3. 运行 (1) Linux用户给IQQ-1 ...
- Eight HDU-1043 (bfs)
Eight Time Limit: 10000/5000 MS (Java/Others) Memory Limit: 65536/32768 K (Java/Others)Total Subm ...
- js读取解析JSON数据(转)
JSON(JavaScript Object Notation) 是一种轻量级的数据交换格式,采用完全独立于语言的文本格式,是理想的数据交换格式.同时,JSON是 JavaScript 原生格式,这意 ...
- python ndarray相关操作:重构
- linux守护进程配置文件
守护进程是一种运行在非交互模式下的程序.一般来说,守护进程任务是和联网区域有关的:它们等待连接,以便通过连接提供服务.Linux 可以使用从 Web 服务器到 ftp 服务器的很多守护进程. /etc ...
- 【CF Manthan, Codefest 17 B】Marvolo Gaunt's Ring
[链接]h在这里写链接 [题意] 给你n个数字; 让你在其中找出三个数字i,j,k(i<=j<=k); 使得p*a[i]+q*a[j]+r*a[k]最大; [题解] /* 有一个要 ...
- 技巧专题3(cdq分治、整体二分等)
cdq分治与整体二分 cdq来源于2008年国家集训队作业陈丹琦(雅礼巨佬),用一个log的代价完成从静态到动态(很多时候是减少时间那一维的). 对于一个时间段[L, R],我们取mid = (L + ...
- NOIP2016提高A组模拟9.28总结
这次三道题都是可以AC的. 每道题思路都正确,但每道题都有细节没有注意. 第一题 1.没注意系数为1时可以省略系数: 2.没注意在第一项处理常数后,不能输出+号. 导致丢失20分:一定要多出特殊数据, ...