Swagger快速上手

这篇具有很好参考价值的文章主要介绍了Swagger快速上手。希望对大家有所帮助。如果存在错误或未考虑完全的地方,请大家不吝赐教,您也可以点击"举报违法"按钮提交疑问。

  • 快速开始:
  1. 导入maven包
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger2</artifactId>
	<version>2.7.0</version>
</dependency>

<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger-ui</artifactId>
	<version>2.7.0</version>
</dependency>
  1. 在启动类配置
# 主启动类
@EnableSwagger2

1. Swagger简介

1、前后端分离:

  • Vue + Springboot 开发模式
  • 后端时代:前端只用管理静态页面;html—>后端。模板引擎 JSP—>后端是主力

2、前后端分离时代:

  • 前端 :前端控制层、视图层【前端团队】
  • 后端:后端控制层、服务层、数据访问层【后端团队】
  • 前后端通过API进行交互【交互方式】
  • 前后端相对独立且松耦合;
  • 前后端甚至可以部署在不同的服务器上

3、产生的问题:

  • 前后端集成,前端或者后端无法做到“及时协商,尽早解决”,最终导致问题集中爆发

4、解决方案

  • 首先定义schema [ 计划的提纲 ],并实时跟踪最新的API,降低集成风险
  • 早些年:指定word计划文档
  • 前后端分离:
    • 前端测试后端接口:postman
    • 后端提供接口,需要实施更新最新的消息及改动!

5、Swagger诞生

  • 号称世界上最流行的API框架
  • Restful Api 文档在线自动生成器 => API 文档 与API 定义同步更新
  • 直接运行,在线测试API
  • 支持多种语言 (如:Java,PHP等)
  • 官网:https://swagger.io/

2. 第一个Swagger程序

1、前期准备

SpringBoot集成Swagger => springfox,两个jar包

  • Springfox-swagger2
  • swagger-springmvc
<!-- 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>

2、项目测试

  1. 创建一个普通的SpringBoot项目,支持web应用
  2. 添加Maven依赖
  3. 编写HelloController,测试确保运行成功!
package com.koko.controller;

import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class HelloController {

    @RequestMapping("/hello")
    public String toHello(){
        return "hello";
    }

}
  1. SwaggerConfig配置类
package com.koko.config;

import org.springframework.context.annotation.Configuration;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration //配置类
@EnableSwagger2// 开启Swagger2的自动配置
public class SwaggerConfig {


}
  1. 测试:http://localhost:8080/swagger-ui.html

Swagger快速上手,后端,spring boot

  • 测试成功!
  • 注意:报错的话更改 spring-boot-starter-parent 版本
<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>2.5.6</version>
    <relativePath/> <!-- lookup parent from repository -->
</parent>

3. Swagger的配置

3.1 配置基本页面

  1. SwaggerConfig配置类中
  • Swagger实例Bean是Docket,所以通过配置Docket实例来配置Swaggger
  • Docket 实例关联上 apiInfo()
@Bean
public Docket docket() {
    return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
}
  • 可以通过apiInfo()属性配置文档信息
//配置文档信息
private ApiInfo apiInfo() {
    Contact contact = new Contact("koko", "http://xxx.xxx.com/联系人访问链接", "联系人邮箱");
    return new ApiInfo(
            "Swagger学习", // 标题
            "学习演示如何配置Swagger", // 描述
            "v1.0", // 版本
            "http://terms.service.url/组织链接", // 组织链接
            contact, // 联系人信息
            "Apach 2.0 许可", // 许可
            "许可链接", // 许可连接
            new ArrayList<>()// 扩展
    );
}
  1. 测试,访问http://localhost:8080/swagger-ui.html

Swagger快速上手,后端,spring boot

3.2 配置扫描接口

  1. SwaggerConfig配置类
@Bean
public Docket docket() {
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            //enable设置是否启动Swagger
            .enable(false)
            //通过.select()方法,去配置扫描接口
            .select()
            //RequestHandlerSelectors配置如何扫描接口
            .apis(RequestHandlerSelectors.basePackage("com.koko.controller"))
            // 配置如何通过path过滤,即这里只扫描请求以/koko开头的接口
            .paths(PathSelectors.ant("/koko/**"))
            .build();
}
  • RequestHandlerSelectors配置的一些方法
any() // 扫描所有,项目中的所有接口都会被扫描到
none() // 不扫描接口
// 通过方法上的注解扫描,如withMethodAnnotation(GetMapping.class)只扫描get请求
withMethodAnnotation(final Class<? extends Annotation> annotation)
// 通过类上的注解扫描,如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口
withClassAnnotation(final Class<? extends Annotation> annotation)
basePackage(final String basePackage) // 根据包路径扫描接口
  • PathSelectors配置的一些方法
any() // 任何请求都扫描
none() // 任何请求都不扫描
regex(final String pathRegex) // 通过正则表达式控制
ant(final String antPattern) // 通过ant()控制

3.3 配置Swagger开关

  1. SwaggerConfig配置类中
@Bean
public Docket docket(Environment environment) {
    // 设置要显示swagger的环境
    Profiles of = Profiles.of("dev", "test");
    // 判断当前是否处于该环境
    // 通过 enable() 接收此参数判断是否要显示
    boolean b = environment.acceptsProfiles(of);

    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            //enable设置是否启动Swagger
            .enable(b)
            //通过.select()方法,去配置扫描接口
            .select()
            //RequestHandlerSelectors配置如何扫描接口
            .apis(RequestHandlerSelectors.basePackage("com.koko.controller"))
            // 配置如何通过path过滤,即这里只扫描请求以/koko开头的接口
            .paths(PathSelectors.ant("/koko/**"))
            .build();
}
  • 通过enable()方法配置是否启用swagger,如果是false,swagger将不能在浏览器中访问了
  • 如何动态配置当项目处于test、dev环境时显示swagger,处于prod时不显示?
  1. 设置配置文件
  • application.properties
spring.profiles.active=dev
  • application-dev.properties(开发环境)
server.port=8081
  • application-pro.properties(发布环境)
server.port=8082
  1. 测试
  • 访问http://localhost:8081/swagger-ui.html时:(开发环境)——>页面正常显示
  • 访问http://localhost:8082/swagger-ui.html时:——>无法访问!!!实现环境改变的功能!!!

3.4 配置API分组

1、实现步骤

  1. 在SwaggerConfig配置类的docket方法中
  • 如果没有配置分组,默认是default。通过groupName()方法即可配置分组
@Bean
public Docket docket(Environment environment) {
   return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
      .groupName("hello") // 配置分组
       // 省略配置....
}
  1. 配置多个分组方法:
  • 配置多个docket
@Bean
public Docket docket1(){
    return new Docket(DocumentationType.SWAGGER_2).groupName("group1");
}
@Bean
public Docket docket2(){
    return new Docket(DocumentationType.SWAGGER_2).groupName("group2");
}
@Bean
public Docket docket3(){
    return new Docket(DocumentationType.SWAGGER_2).groupName("group3");
}
  1. 测试:http://localhost:8081/swagger-ui.html

Swagger快速上手,后端,spring boot

3.5 常见注解

1、注解的简单说明

  • Swagger的所有注解定义在io.swagger.annotations包下(下面是常见的)
    | Swagger注解 | 简单说明 |
    | — | — |
    | [@Api(tags ](/Api(tags )
    = “xxx模块说明”) | 作用在模块类上 |
    | @ApiOperation(“xxx接口说明”) | 作用在接口方法上 |
    | @ApiModel(“xxxPOJO说明”) | 作用在模型类上:如VO、BO |
    | [@ApiModelProperty(value ](/ApiModelProperty(value )
    = “xxx属性说明”,hidden = true) | 作用在类方法和属性上,hidden设置为true可以隐藏该属性 |
    | @ApiParam(“xxx参数说明”) | 作用在参数、方法和字段上,类似@ApiModelProperty |

2、举例讲解上述五个注解

  • 以注释了序号,可以和上述表对应!
  1. HelloController页面控制跳转类
package com.koko.controller;

import com.koko.pojo.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;

@Api(tags = "1、模块类")
@RestController
public class HelloController {

    @GetMapping("/hello")
    public String hello(){
        return "hello";
    }

    @PostMapping("/user")
    public User user(){
        return new User();
    }

    @ApiOperation("2、接口方法")
    @GetMapping("/hello02")
    public String toHello02(@ApiParam("5、接口中的参数、方法和字段") String username){
        return "hello" + username;
    }

}
  1. User实体类
package com.koko.pojo;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel("3、模型类(实体类)")
public class User {

    @ApiModelProperty("4、属性-用户名")
    public String username;

    @ApiModelProperty("4、属性-密码")
    public String password;

}
  1. 测试

Swagger快速上手,后端,spring boot

  • 在模块类中

Swagger快速上手,后端,spring boot

  • 在实体类模型中

Swagger快速上手,后端,spring boot

拓展:皮肤

  1. 默认的  **访问 **http://localhost:8080/swagger-ui.html
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger-ui</artifactId>
   <version>2.9.2</version>
</dependency>

Swagger快速上手,后端,spring boot

  1. bootstrap-ui  **访问 **http://localhost:8080/doc.html
<!-- 引入swagger-bootstrap-ui包 /doc.html-->
<dependency>
   <groupId>com.github.xiaoymin</groupId>
   <artifactId>swagger-bootstrap-ui</artifactId>
   <version>1.9.1</version>
</dependency>

Swagger快速上手,后端,spring boot

  1. Layui-ui  **访问 **http://localhost:8080/docs.html
<!-- 引入swagger-ui-layer包 /docs.html-->
<dependency>
   <groupId>com.github.caspar-chen</groupId>
   <artifactId>swagger-ui-layer</artifactId>
   <version>1.1.3</version>
</dependency>

Swagger快速上手,后端,spring boot

  1. mg-ui  **访问 **http://localhost:8080/document.html
<!-- 引入swagger-ui-layer包 /document.html-->
<dependency>
   <groupId>com.zyplayer</groupId>
   <artifactId>swagger-mg-ui</artifactId>
   <version>1.0.6</version>
</dependency>

Swagger快速上手,后端,spring boot

总结

  1. 我们可以通过Swagger给一些比较难理解的属性或者接口,增加注释信息
  2. 接口文档要实时更新
  3. 可以在线测试

Swagger是一个优秀的工具,几乎所有大公司都有使用它!
【注意点】在正式发布的时候,关闭Swagger!!!处于安全考虑,也同时节省运行内存!!!文章来源地址https://www.toymoban.com/news/detail-756789.html

到了这里,关于Swagger快速上手的文章就介绍完了。如果您还想了解更多内容,请在右上角搜索TOY模板网以前的文章或继续浏览下面的相关文章,希望大家以后多多支持TOY模板网!

本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如若转载,请注明出处: 如若内容造成侵权/违法违规/事实不符,请点击违法举报进行投诉反馈,一经查实,立即删除!

领支付宝红包 赞助服务器费用

相关文章

  • Spring Boot 中如何使用 Swagger

    在开发 Web 应用时,API 文档的编写和维护是一项非常重要的工作。Swagger 是一款非常流行的 API 文档工具,可以自动生成 API 文档,并提供一系列的交互式工具,如测试界面、调试界面等,方便开发者进行 API 的调试和测试。本文将介绍如何在 Spring Boot 应用中使用 Swagger。 首先

    2024年02月11日
    浏览(43)
  • spring boot 集成 swagger3

              Swagger 3是一种开源的API描述工具,它可以帮助开发人员设计、构建、文档化和测试API。Swagger 3支持多种编程语言和框架,包括Java、Node.js、Python、Ruby等,并提供了许多集成工具和插件,例如Postman、Apigee等。 Swagger 3使用OpenAPI规范来描述API,这是一种通用的API描述

    2024年02月06日
    浏览(43)
  • Spring Boot整合Spring Fox生成Swagger文档

    Springfox是一个用于在Spring应用程序中生成Swagger文档的开源库。它提供了一组注解和工具,可以将你的API代码和文档整合在一起,方便生成和展示API的Swagger文档。 使用Springfox,你可以在Spring Boot项目中集成Swagger,并通过Swagger UI查看和测试API。它提供了一些注解,如 @Api 、 @

    2024年02月08日
    浏览(44)
  • swagger 2.10.5 整合 spring boot

    2024年02月11日
    浏览(41)
  • Spring Boot 整合 Swagger2 纠错

            因为我要建立的是微服务的项目,需要建立许多模块,以至于我在父工程中引入了当前模块,然后我在子模块中又引入了当前模块,造成了冲突。         另外一种解决方法是,经过上网查证,可能由于Spring Boot和Swagger版本的问题,Spring Boot2.6以上的版本,需要使用

    2024年02月12日
    浏览(41)
  • Spring Boot 禁用 Swagger 的三种方式

    禁用方法1: ====== 使用注解 @Value() 推荐使用 package com.dc.config; import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry; impo

    2024年04月22日
    浏览(47)
  • Spring Boot 3项目集成Swagger3教程

    欢迎来到我的小天地,这里是我记录技术点滴、分享学习心得的地方。📚 🛠️ 技能清单 编程语言 :Java、C、C++、Python、Go、 前端技术 :Jquery、Vue.js、React、uni-app、Echarts UI设计 : Element-ui、Antd、Color-ui 后端技术 :Spring Boot、Mybatis-plus、Swagger 移动开发 :Android 操作系统 :

    2024年04月17日
    浏览(57)
  • spring boot未授权访问及Swagger漏洞处理

    无需修改源码,处理spring boot未授权访问及Swagger漏洞处理 风险程度 :【高危】 漏洞概述 : 未授权访问可以理解为需要安全配置或权限认证的地址、授权页面存在缺陷,导致其他用户可以直接访问,从而引发重要权限可被操作、数据库、网站目录等敏感信息泄露。登陆验证一

    2024年02月16日
    浏览(42)
  • spring boot 2.7.9 整合 Swagger 3.0

     jdk  1.8 springboot 2.7.9 swagger 3.0.0 描述:Failed to start bean \\\'documentationPluginsBootstrapper\\\'; nested exception is java.lang.NullPointerException 没有这个bean,空指针了。 据网上资料找,3.0的Swagger已经不继承WebMvcConfig这个类,是继承了WebMvcConfigSupport类,从而改动了配置路径规则,然后报空指针,

    2024年02月06日
    浏览(79)
  • Spring boot 启动添加访问地址和swagger地址输出

             在Spring boot 项目启动后,输出访问地址和swagger地址,便于查看和对接。 通过Environment去读取配置的名称,端口和路径。 启动后,就可以看到输出的内容,可以直接访问swagger就比较方便。

    2024年01月23日
    浏览(42)

觉得文章有用就打赏一下文章作者

支付宝扫一扫打赏

博客赞助

微信扫一扫打赏

请作者喝杯咖啡吧~博客赞助

支付宝扫一扫领取红包,优惠每天领

二维码1

领取红包

二维码2

领红包