swagger接口文档使用
swagger接口文档
- 一,swagger简介
- 前后端分离
- swagger 诞生
- 二,springboot集成swagger
- 依赖
- 编写helloworld接口
- 配置swagger ==> config 配置类
- 测试运行
- 三,配置swagger
- swagger 配置扫描接口
- 如何做到只在生产环境中启动swagger?
- 配置api文档的分组
- 四,swagger注解用于对实体类,接口的描述
- pojo
- controller
- 五,你以为的是swagger只能提供接口描述信息?呵~
- swagger能测试呀
- 六,最后
一,swagger简介
前后端分离
vue + springboot 一套解决方案
后端时代:前端只用管理静态页面;html===>后端。模板引擎 jsp ejb 后端是主力
前后端分离时代:
- 后端:后端控制层,服务层,数据访问层 【后端团队】
- 前端:前端控制层(双向绑定),视图层【前端团队】
- 伪造后端数据,json。已经存在,无需后端,全段工程依旧能够跑起来。
- 前后端如何交互?===> API json
- 前后端相对独立,松耦合
- 前后端可用部署在不同的服务器上
前后端分离产生,一个问题
- 前后端集成联调,前端和后端人员无法做到,”即时协商,尽早解决“,最终导致问题集中爆发
解决方法:
指定schema 【计划的提纲】。实时更新最新api,降低集成的风险;
早些年:制定word计划文档;
前后端分离:
- 前端测试后端接口:postman
- 后端提供接口,需要实时更新最新的消息及改动!
swagger 诞生
- 号称世界上最流行的api框架
- restful api文档在线自动生成工具=> api 文档与api定义同步更更新
- 直接运行,在线测试api接口
- 支持多种语言 java,php,py…
官网:https://swagger.io
在项目中使用swagger springbox
- swagger2
- ui
二,springboot集成swagger
依赖
导入相关依赖
- springfox-swagger2
- springfox-swagger-ui
pom
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 --> <dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.9.2</version> </dependency><!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui --> <dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.9.2</version> </dependency>
编写helloworld接口
package cn.bitqian.swagger.controller;import org.springframework.web.bind.annotation.*;/*** hello world* @author echo lovely* @date 2020/10/28 19:23*/
@RestController
public class HelloController {@RequestMapping(value = "/hello")public String hello() {return "hello";}}
配置swagger ==> config 配置类
开启swagger,Enablexxx
@Configuration
@EnableSwagger2 // 开启swagger2
public class SwaggerConfig {}
测试运行
http://localhost:8080/swagger-ui.html
三,配置swagger
来告诉交接人员,接口是干嘛的,对controller的接口进行描述。也可以设置接口访问权限。
package cn.bitqian.swagger.config;import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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.ArrayList;/*** swagger配置类* @author echo lovely* @date 2020/10/28 19:35*/
@Configuration
@EnableSwagger2 // 开启swagger2
public class SwaggerConfig {// 文档的标题,和描述!作者的信息deng..@Beanpublic Docket docket() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(appInfo());}// api 信息 接口文档的头部信息描述public ApiInfo appInfo() {Contact contact = new Contact("bitqian", "http://example.com", "admin-@www.example.cn");return new ApiInfo("bitqian的swagger文档","用来描述此接口的功能,内容。","v1.0","http://example.cn", contact,"Apache 2.0","http://www.apache.org/licenses/LICENSE-2.0",new ArrayList());}}
swagger 配置扫描接口
@Beanpublic Docket docket() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(appInfo()).select().// RequestHandlerSelectors 配置要扫描的接口的方式// basePackage 指定要扫描的包// any() 扫描全部// none() 不扫描// withClassAnnotation(Controller.class) 扫描类上的注解, 生效// withMethodAnnotation(RequestMapping.class) 扫描方法上的注解, 生效apis(RequestHandlerSelectors.basePackage("cn.bitqian.swagger.controller")).// paths(PathSelectors.ant("/bitqian/**")) 扫描指定的接口// PathSelectors.regex("")paths(PathSelectors.ant("/hello/**")).build();}
如何做到只在生产环境中启动swagger?
- 判断是否是生产环境
- 注入enable
@Beanpublic Docket docket(Environment environment) {// 获取当前环境 是生产环境 启动swaggerboolean isProFlag = environment.acceptsProfiles(Profiles.of("pro"));System.out.println("is dev environment....===========>" + isProFlag);return new Docket(DocumentationType.SWAGGER_2).apiInfo(appInfo()).groupName("bitqian").enable(isProFlag). // 是否启动swagger 如果为false,则不能在浏览器中使用swaggerselect().apis(RequestHandlerSelectors.basePackage("cn.bitqian.swagger.controller")).// paths(PathSelectors.ant("/hello/**")).build();}
配置api文档的分组
- 整出多个docket,多个人写不同的接口
@Bean
public Docket docket1() {return new Docket(DocumentationType.SWAGGER_2).groupName("bitqian666 group1");
} @Bean
public Docket docket12() {return new Docket(DocumentationType.SWAGGER_2).groupName("bitqian666 group2");
}
四,swagger注解用于对实体类,接口的描述
pojo
package cn.bitqian.swagger.entity;import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;/*** 给实体类生成文档* @author echo lovely* @date 2020/10/29 21:09*/
@ApiModel("user实体类")
public class User {@ApiModelProperty("用户名")public String username;@ApiModelProperty("密码")public String password;public User() {}public User(String username, String password) {this.username = username;this.password = password;}
}
controller
package cn.bitqian.swagger.controller;import cn.bitqian.swagger.entity.User;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.*;/*** hello world* @author echo lovely* @date 2020/10/28 19:23*/
@RestController
public class HelloController {@ApiOperation("get/post都可的hello接口")@RequestMapping(value = "/hello")public String hello() {return "hello";}@ApiOperation("get的hello接口, 返回一个空 user")@GetMapping(value = "/hello1")public User hello1() {return new User();}@ApiOperation("hello1 接口post way~")@PostMapping(value = "/hello1")public User hello1(@ApiParam("传递用户") User user) {return user;}@ApiOperation("登录接口 post way~")@PostMapping(value = "/login")public String login(@ApiParam("登录用户名") @RequestParam("username") String username,@ApiParam("登录密码") @RequestParam("password") String password) {return "ok" + "{" + username + ", " + password + "}";}}
五,你以为的是swagger只能提供接口描述信息?呵~
swagger能测试呀
try it out
六,最后
- 我们可用通过swagger给一些比较难理解的属性或者接口,增加注释信息
- 接口文档实时更新
- 可以在线测试
swagger是一个优秀的工具,几乎所有大公司都有使用它,更符合迭代开发的需求。
【注意点】 在正式发布的时候,关闭swagger!!!处于安全考虑。而且节省运行的内存。
swagger接口文档使用相关推荐
- sentinel 官方文档_SpringCloud网关聚合Swagger接口文档实践
目前大多数项目都是以微服务架构设计,以前后端分离技术解耦前端开发工程师和后端开发工程师的工作量,这样一来前后端的对接将是一项重要的沟通工作量,如果后端没有一个合适的API文档,那么这样的前后端对接将是 ...
- springboot 接口文档 请求 enum_Spring Boot集成SpringFox 3:生成Swagger接口文档
SpringFox介绍 SpringFox是一个开源的API Doc的框架, 它的前身是swagger-springmvc,可以将我们的Controller中的方法以文档的形式展现.官方定义为:Aut ...
- 整合Swagger接口文档
Swagger接口文档:自动生成接口文档 1.添加依赖: <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagg ...
- 自动生成python接口文档_Django自动生成Swagger接口文档
Django自动生成Swagger接口文档 1. 前言 当接口开发完成,紧接着需要编写接口文档.传统的接口文档通常都是使用Word或者一些接口文档管理平台进行编写,但此类接口文档维护更新比较麻烦,每次 ...
- swagger接口文档出现的空文档问题
记一次使用swagger接口文档出现的空文档问题 问题描述: 上面显示的一些空文档 下面的才是真正的正确文档: 最终尝试发现问题: 原因:**@Api(value = "ExamPaperC ...
- SpringBoot集成knife4j实现Swagger接口文档
前言:如果你是后台开发,提供restful接口给前端,建议你使用Swagger3提供restful的接口文档自动生成和在线接口调试.knife4j是对Swagger进一步封装,其优化了API文档的UI ...
- python实现处理swagger接口文档,转换为yaml格式的自动化用例
前言 之前有很多小伙伴反馈,希望我出一期 将swagger文档转换为 yaml格式的自动化用例,那么本期福利来咯~~这一篇文档,将会带领你们实现 如何通过 swagger文档转换为 yaml格式的用例 ...
- Python Swagger 接口文档自动集成平台
一 安装 当前virtualenv 环境下 pip install django-rest-swagger==2.2.0 在Django项目settings.py中 加入 插件模块 DEBUG = T ...
- 【愚公系列】2023年02月 WMS智能仓储系统-007.Swagger接口文档的配置
文章目录 前言 一.Swagger接口文档的配置 1.安装包 2.注入 2.1 Swagger服务的注入 2.2 appsetting.json的配置 2.3 Swagger服务的封装 2.3.1 S ...
最新文章
- 《C和指针》对于数组这一节的总结
- R语言应用实战系列(六)-基于R的人工神经网络ANN算法和KNN算法(k-Nearest Neighbour)
- 1968: [Ahoi2005]COMMON 约数研究
- 在JavaScript函数中使用EL表达式注意的事项
- 七、有机硅柔软剂在不同发展阶段分子结构特征及主要解决的问题?
- win10 安装docker
- 详解Intellij IDEA中.properties文件中文显示乱码问题的解决
- [C#] 如何分析stackoverflow等clr错误
- 远程协助计算机是灰色的,服务器远程协助是灰色的
- latex \textsuperscript{\dagger} 报错
- SQL Where 字符串拼接
- 费波纳奇数c语言,费波纳切数列用C语言怎么编程
- python超清壁纸_Python爬取5K分辨率超清唯美壁纸
- 恶魔奶爸语法10-12课
- 主仆渡河问题 ----python
- java图书商城项目_JavaWeb之网上图书商城-框架搭建
- 微型计算机2018年12月,2018年度金奖TOP 10:出类拔萃的产品都在这!
- 欧阳的科研历程-1 目标
- Chrome浏览器各种崩溃、卡死解决方法
- QString自动补全