Springfox Swagger2从入门到精通

news2024/10/7 6:47:59

概述：Swagger 是一种用于设计、构建、文档化和使用 RESTful API 的工具。Springfox 是 Swagger 在 Spring 应用中的集成库，提供了自动生成 API 文档的功能。在本文中，我们将探讨如何使用 Springfox Swagger2 在 Spring Boot 项目中生成、配置和使用 API 文档

目录

1. 引入依赖

2. 配置 Swagger2

3. 启用 Swagger2

4. 编写 API 文档注释

5. 访问 Swagger UI

6、Springfox Swagger2常用注解分析

7. 高级配置

结论

1. 引入依赖

首先，确保在项目的 pom.xml 文件中引入 Springfox Swagger2 的依赖：

<!-- Swagger2 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>

        <!-- Swagger UI -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

2. 配置 Swagger2

在 Spring Boot 项目中，我们需要配置 Swagger2，告诉它在哪里扫描 API，并如何显示文档。创建一个配置类，例如 SwaggerConfig.java：

package org.example.testdoc.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;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("org.example.testdoc.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Springfox Swagger2 Example")
                .description("This is an example of using Springfox Swagger2 to generate API documentation.")
                .version("1.0")
                .build();
    }
}

在这个配置类中，我们使用 @Configuration 注解标记它为配置类

  1. 定义了一个名为api()的方法，该方法返回一个Docket对象，用于配置Swagger。

    • DocumentationType.SWAGGER_2指定了文档类型为Swagger 2。
    • apiInfo()方法用于构建API文档的基本信息，包括标题、描述和版本号。
    • select()方法用于选择要生成文档的API路径和控制器类。
      • apis(RequestHandlerSelectors.basePackage("org.example.testdoc.controller"))指定了扫描的包路径为"org.example.testdoc.controller"，即只扫描该包下的控制器类。
      • paths(PathSelectors.any())表示生成文档包含所有的API路径。
    • build()方法完成构建过程。

  2. apiInfo()方法定义了一个私有方法，用于构建API文档的基本信息。

    • ApiInfoBuilder用于构建API文档的信息。
    • title("Springfox Swagger2 Example")设置文档的标题为"Springfox Swagger2 Example"。
    • description("This is an example of using Springfox Swagger2 to generate API documentation.")设置文档的描述信息。
    • version("1.0")设置文档的版本号为"1.0"。
    • build()方法完成构建过程。

编写配置文件：

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

3. 启用 Swagger2

在主应用程序类中使用 @EnableSwagger2 注解启用 Swagger2：

package org.example.testdoc;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@SpringBootApplication
@EnableSwagger2
public class TestdocApplication {

    public static void main(String[] args) {
        SpringApplication.run(TestdocApplication.class, args);
    }

}

现在，当你启动应用程序时，Swagger2 将自动在 http://localhost:8080/swagger-ui.html 上生成 API 文档。

4. 编写 API 文档注释

为了让生成的 API 文档更加详细和清晰，我们需要在控制器类和方法上添加 Swagger2 注解。例如：

package org.example.testdoc.controller;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@Api(value = "Example Controller", tags = "example")
@RestController
public class ExampleController {
    @ApiOperation(value = "Get example data", notes = "This API returns example data.")
    @GetMapping("/example")
    public String getExampleData() {
        return "Hello, World!";
    }
}

  1. 使用@Api注解标记该类为API文档的一部分，并设置文档的标题和标签。

    • value = "Example Controller"设置文档的标题为"Example Controller"。
    • tags = "example"设置文档的标签为"example"。

  2. 使用@RestController注解将该类标记为RESTful风格的控制器。

  3. 定义一个名为getExampleData()的方法，用于处理HTTP GET请求。

    • 使用@ApiOperation注解标记该方法为API文档的一部分，并设置方法的描述信息。
      • value = "Get example data"设置方法的描述为"Get example data"。
      • notes = "This API returns example data."设置方法的备注信息为"This API returns example data."。
    • 使用@GetMapping("/example")注解指定该方法处理的URL路径为"/example"。
    • 方法返回一个字符串"Hello, World!"作为示例数据。

5. 访问 Swagger UI

现在，启动你的 Spring Boot 应用程序，并访问 http://localhost:8080/swagger-ui.html。你将看到生成的 API 文档，可以在此交互式界面中测试和查看你的 API。

6、Springfox Swagger2常用注解分析

@Api：用于标记一个类为API文档的主体，可以设置文档的标题、描述、版本等信息。例如：

@Api(value = "User Controller", description = "Operations pertaining to user")
public class UserController {
    // ...
}

@ApiOperation：用于描述一个方法的操作信息，包括操作的名称、描述、返回值等。例如：

@ApiOperation(value = "Get user by id", notes = "Returns a user")
@GetMapping("/users/{id}")
public User getUserById(@PathVariable Long id) {
    // ...
}

@ApiParam：用于描述一个方法的参数信息，包括参数的名称、描述、数据类型等。例如：

@ApiOperation(value = "Create a new user")
@PostMapping("/users")
public void createUser(@ApiParam(value = "User object", required = true) @RequestBody User user) {
    // ...
}

@ApiModel：用于定义一个模型类，用于描述复杂类型的结构。例如：

@ApiModel(description = "User details")
public class User {
    // ...
}

@ApiModelProperty：用于描述一个模型类的属性信息，包括属性的名称、描述、数据类型等。例如：

@ApiModel(description = "User details")
public class User {
    @ApiModelProperty(value = "The user's name", required = true)
    private String name;
    // ...
}

@ApiResponse：用于描述一个API响应的信息，包括响应的状态码、描述等。例如：

@ApiResponses(value = {
    @ApiResponse(code = 200, message = "Success"),
    @ApiResponse(code = 404, message = "Not found")
})

@ApiIgnore：用于忽略某个API接口或参数，不生成文档。例如：

@ApiIgnore
@GetMapping("/hidden")
public String hiddenEndpoint() {
    // ...
}

@ApiImplicitParam：用于描述一个隐式参数的信息，包括参数的名称、描述、数据类型等。例如：

@ApiOperation(value = "Search users", notes = "Passes the query as a parameter")
@GetMapping("/users/search")
public List<User> searchUsers(@ApiImplicitParam(name = "query", value = "Search query", required = true, dataType = "string") String query) {
    // ...
}

@ApiImplicitParams：用于描述多个隐式参数的信息。例如：

@ApiOperation(value = "Search users", notes = "Passes multiple parameters")
@GetMapping("/users/search")
public List<User> searchUsers(@ApiImplicitParams({
    @ApiImplicitParam(name = "query", value = "Search query", required = true, dataType = "string"),
    @ApiImplicitParam(name = "page", value = "Page number", required = false, dataType = "int")
}) String query, @RequestParam(required = false) Integer page) {
    // ...
}

7. 高级配置

Springfox Swagger2 提供了丰富的配置选项，允许你自定义生成的文档。你可以配置 API 标题、描述、联系信息等。详细配置可以参考 Springfox 文档。

结论

通过集成 Springfox Swagger2，我们可以方便地生成、查看和测试 API 文档。这对于团队协作、前后端协调以及 API 的开发和维护都是非常有益的。希望这篇文章能帮助你入门并更好地利用 Swagger2 在 Spring Boot 项目中管理 API 文档。

本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若转载，请注明出处：http://www.coloradmin.cn/o/1411862.html

如若内容造成侵权/违法违规/事实不符，请联系多彩编程网进行投诉反馈，一经查实，立即删除！

相关文章

使用json-server提供简易接口

使用json-server提供简易接口

json-server是一款 json 数据服务器&#xff0c;它运行 Express 服务器&#xff0c;可以对json文件、js脚本生成的json数据、远程json数据进行restful风格的增删改查操作&#xff0c;通过指定一个json文件作为api数据源&#xff0c;可以进行分页、排序、关联查询、范围查询等各…
阅读更多...
紫光展锐M6780丨超分辨率技术——画质重构还原经典

紫光展锐M6780丨超分辨率技术——画质重构还原经典

上一期&#xff0c;我们揭秘了让画质更加炫彩的AI-PQ技术。面对分辨率较低的老电影&#xff0c;光有高饱和度的色彩是不够的&#xff0c;如何能够提高视频影像的分辨率&#xff0c;使画质更加清晰&#xff0c;实现老片新看&#xff1f; 本期带大家揭晓紫光展锐首颗AI8K超高清智…
阅读更多...
数据安全之对称加密（九）- 数据填充实现

数据安全之对称加密（九）- 数据填充实现

AES 是一种采用分组加密方法的算法。待加密的明文首先被分割成若干固定大小的块&#xff0c;每个块大小通常是128位。接着&#xff0c;这些块逐一被加密&#xff0c;转换成对应的密文块。这种处理方式确保了加密的一致性和效率&#xff0c;同时也方便了对数据的管理和加密处理。…
阅读更多...
从物联网看智慧文旅的未来：技术与实践的完美结合，重塑旅游体验的新篇章

从物联网看智慧文旅的未来：技术与实践的完美结合，重塑旅游体验的新篇章

一、物联网技术&#xff1a;智慧文旅的基石 随着科技的飞速发展&#xff0c;物联网技术已经深入到我们生活的方方面面&#xff0c;尤其在智慧文旅领域&#xff0c;物联网技术更是起到了不可或缺的作用。它如同智慧文旅的基石&#xff0c;为旅游行业带来了前所未有的创新和变革…
阅读更多...
基于Java SSM框架实现大学生社团管理系统项目【项目源码+论文说明】计算机毕业设计

基于Java SSM框架实现大学生社团管理系统项目【项目源码+论文说明】计算机毕业设计

基于java的SSM框架实现大学生社团管理系统演示 摘要 在网络迅速发展的时代&#xff0c;众多的软件被开发出来&#xff0c;给社团带来了很大的选择余地&#xff0c;而且学生越来越追求更个性的需求。在这种时代背景下&#xff0c;社团只能以学生为导向&#xff0c;按学生所需要…
阅读更多...
AMEYA360--思瑞浦推出16通道高精度ADC—TPAFE51760

AMEYA360--思瑞浦推出16通道高精度ADC—TPAFE51760

聚焦高性能模拟芯片和嵌入式处理器研发的半导体公司——思瑞浦推出全新16通道高精度ADC——TPAFE51760。 TPAFE51760内置高精度基准&#xff0c;工作温度支持-40C to 125C&#xff0c;产品广泛应用于电力自动化领域中的DTU、FTU、MU等装置。 TPAFE51760产品优势 业界领先的30V模…
阅读更多...
成本更低、更可控，云原生可观测新计费模式正式上线

成本更低、更可控，云原生可观测新计费模式正式上线

云布道师 在上云开始使用云产品过程中&#xff0c;企业一定遇见过两件“讨厌”事&#xff1a; 难以理解的复杂计费逻辑&#xff0c;时常冒出“这也能收费”的感叹&#xff1b; 某个配置参数调节之后&#xff0c;云产品使用成本不可预估的暴涨。 可观测作为企业 IT 运维必须品…
阅读更多...
Redis系列-数据结构篇

Redis系列-数据结构篇

数据结构 string&#xff08;字符串&#xff09; redis的字符串是动态字符串&#xff0c;类似于ArrayList&#xff0c;采用预分配冗余空间的方式减少内存的频繁分配。 struct SDS<T>{ T capacity; T len; byte flags; byte[] content; } 当字符串比较短时&#xff0c…
阅读更多...
在 Vue 项目中，可以通过设置不同的环境变量来区分不同的环境，例如本地开发环境、测试环境和生产环境。以下是设置环境变量的步骤：

在 Vue 项目中，可以通过设置不同的环境变量来区分不同的环境，例如本地开发环境、测试环境和生产环境。以下是设置环境变量的步骤：

1、在src下新建三个文件夹 &#xff08;.env.local、.env.test 和 .env.prod&#xff09; 2、配置信息 .env.local VUE_APP_ENVlocal VUE_APP_API_URLhttp://localhost:8080.env.test VUE_APP_ENVtest VUE_APP_API_URLhttp://124.220.110.203:9090/ .env.prod VUE_APP_…
阅读更多...
直播主播产品转场话术

直播主播产品转场话术

主播产品转场话术 一、预告下一环节 亲爱的观众朋友们&#xff0c;非常感谢大家对我们直播间的关注与支持!现在&#xff0c;我们即将进入下一个环节&#xff0c;这个环节将为您带来更多惊喜!请耐心等待&#xff0c;不要离开哦! 二、解释过渡 感谢大家对我们产品的喜爱与支持…
阅读更多...
循环测试之旅——深度解析Pytest插件 pytest-repeat

循环测试之旅——深度解析Pytest插件 pytest-repeat

在软件开发中，测试的重要性不言而喻。而为了提高测试的鲁棒性和可靠性，Pytest插件 pytest-repeat 应运而生。这个插件可以帮助你轻松实现测试用例的循环运行，以更全面地评估代码的稳定性。本文将深入介绍 pytest-repeat 插件的基本用法和实际案例，助你更好地利用循环测试，…
阅读更多...
JavaSE基础详细总结

JavaSE基础详细总结

JavaSE基础总结 目录 初始Java数据类型和变量运算符逻辑控制方法数组类和对象继承和多态抽象类和接口String异常 1、初始java Java之父——詹姆斯.高斯林 Java语言的命名&#xff08;爪哇岛。盛产咖啡&#xff09;和咖啡图标都反映了詹姆斯。高斯林热爱咖啡。 1、“一次编…
阅读更多...
SpringBoot高级原理

SpringBoot高级原理

SpringBoot高级原理 今日内容&#xff1a; 理解SpringBoot自动化配置源码理解SpringBoot健康监控 1 SpringBoot自动化配置原理 01-SpringBoot2高级-starter依赖管理机制 目的&#xff1a;通过依赖能了解SpringBoot管理了哪些starter 讲解&#xff1a; 通过依赖 spring-bo…
阅读更多...
外汇天眼：新坦利斯曼黄金矿业的前首席执行官承认违反新西兰金融市场法

外汇天眼：新坦利斯曼黄金矿业的前首席执行官承认违反新西兰金融市场法

新西兰金融市场管理局&#xff08;FMA&#xff09;今天确认&#xff0c;新西兰证券交易所上市公司新坦利斯曼黄金矿业有限公司的前首席执行官Matthew Geoffrey Hill承认违反了2013年《金融市场行为法》&#xff08;FMCA&#xff09;&#xff0c;在此法案下作出了虚假和误导性陈…
阅读更多...
Linux本地部署SVN服务结合内网穿透实现远程访问

Linux本地部署SVN服务结合内网穿透实现远程访问

文章目录 前言1. Ubuntu安装SVN服务2. 修改配置文件2.1 修改svnserve.conf文件2.2 修改passwd文件2.3 修改authz文件 3. 启动svn服务4. 内网穿透4.1 安装cpolar内网穿透4.2 创建隧道映射本地端口 5. 测试公网访问6. 配置固定公网TCP端口地址6.1 保留一个固定的公网TCP端口地址6…
阅读更多...
【wink】如何导出Live实况？

【wink】如何导出Live实况？

1.首页点击「转Live实况」&#xff0c;即可将图片或视频快速转为Live实况格式。 2.编辑后的视频&#xff0c;可在保存分享页点击「存为Live实况」。&#xff08;本功能仅限iOS用户使用&#xff09;
阅读更多...
【每日一题】4.LeetCode——杨辉三角

【每日一题】4.LeetCode——杨辉三角

&#x1f4da;博客主页&#xff1a;爱敲代码的小杨. ✨专栏&#xff1a;《Java SE语法》 ❤️感谢大家点赞&#x1f44d;&#x1f3fb;收藏⭐评论✍&#x1f3fb;&#xff0c;您的三连就是我持续更新的动力❤️ &#x1f64f;小杨水平有限&#xff0c;欢迎各位大佬指点&…
阅读更多...
佩戴口罩监测识别摄像机

佩戴口罩监测识别摄像机

佩戴口罩监测识别摄像机是一种基于计算机视觉技术的智能监测设备&#xff0c;它能够快速准确地识别出人们是否佩戴口罩&#xff0c;并对佩戴口罩的人员进行识别和记录。这种摄像机在当前抗击病毒的背景下具有重要意义&#xff0c;在公共场所、医疗机构、交通枢纽等地方都有着广…
阅读更多...
Gradle学习笔记：Gradle的使用方法

Gradle学习笔记：Gradle的使用方法

文章目录 1.初始化项目2.构建脚本语言选择3.项目命名4.项目构建过程 1.初始化项目 创建一个test空文件夹&#xff0c;在该文件夹下打开终端&#xff0c;并执行命令&#xff1a;gradle init. 会有一个选项让你选择项目的类型。下面是每个选项的含义和用途&#xff1a; basic&am…
阅读更多...
cg插画设计行业怎么样，如何学习插画设计

cg插画设计行业怎么样，如何学习插画设计

插画设计行业是一个充满创意和艺术性的行业&#xff0c;随着数字化时代的不断发展&#xff0c;cg插画的应用范围越来越广泛&#xff0c;市场需求也在逐年增长。以下是一些关于acg插画设计行业的现状和发展趋势&#xff1a; 市场需求不断增长&#xff1a;随着广告、媒体、影视、…
阅读更多...
推荐文章
最新文章

Copyright @ 2022~2023