Swagger学习

本文介绍了如何在SpringBoot项目中整合Swagger2,包括添加依赖、配置文档信息,以及通过Swagger2Markup将Swagger文档转换为静态格式。同时,文章提到了使用SpringFox 3生成Swagger文档的方法,并提供了相关API的说明注解。

摘要生成于 C知道 ,由 DeepSeek-R1 满血版支持, 前往体验 >

Swagger

SpringBoot整合Swagger2:

  1. 添加swagger-spring-boot-starter依赖

    <dependency>    
        <groupId>com.spring4all</groupId>
        <artifactId>swagger-spring-boot-starter</artifactId》
        <version>1.9.0.RELEASE</version>
    </dependency>
    
  2. 应用主类中添加@EnableSwagger2Doc注解

  3. application.properties中配置文档相关内容,如:

    swagger.title=spring-boot-starter-swagger
    swagger.description=Starter for swagger 2.x
    swagger.version=1.4.0.RELEASE
    swagger.license=Apache License, Version 2.0
    swagger.licenseUrl=https://www.apache.org/licenses/LICENSE-2.0.html
    swagger.termsOfServiceUrl=https://github.com/dyc87112/spring-boot-starter-swagger
    swagger.contact.name=didi
    swagger.contact.url=http://blog.didispace.com
    swagger.contact.email=dyc87112@qq.com
    swagger.base-package=com.didispace
    swagger.base-path=/**
    

    各参数配置含义如下:

    • swagger.title:标题
    • swagger.description:描述
    • swagger.version:版本
    • swagger.license:许可证
    • swagger.licenseUrl:许可证URL
    • swagger.termsOfServiceUrl:服务条款URL
    • swagger.contact.name:维护人
    • swagger.contact.url:维护人URL
    • swagger.contact.email:维护人email
    • swagger.base-package:swagger扫描的基础包,默认:全扫描
    • swagger.base-path:需要处理的基础URL规则,默认:/**
  4. 启动应用,访问:http://localhost:8080/swagger-ui.html

  5. @Api(tags="")@ApiOperation("value="")注解来给API增加说明、通过@ApiImplicitParam@ApiModel@ApiModelProperty注解来给参数增加说明。

在这里插入图片描述

在这里插入图片描述

Swagger2Markup简介

Swagger2Markup是Github上的一个开源项目。该项目主要用来将Swagger自动生成的文档转换成几种流行的格式以便于静态部署和使用,比如:AsciiDoc、Markdown、Confluence。

使用SpringFox 3生成Swagger文档

  1. 添加依赖

    <dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
    </dependency>
    
  2. 应用主类增加注解@EnableOpenApi(上面的方式是用@EnableSwagger2Doc

  3. 其余注解相同

  4. 启动应用!访问swagger页面:http://localhost:8081/swagger-ui/index.html

  5. 两个可访问路径:http://host/context-path/swagger-ui/index.htmlhttp://host/context-path/swagger-ui/,以前老版本的文档接口/v2/api-docs之外,还多了一个新版本的/v3/api-docs接口。

### 关于 Swagger学习教程 Swagger 是一种用于设计、构建和记录 RESTful API 的工具集。它支持多种编程语言和框架,例如 Java、Python、Node.js 和 Ruby 等[^1]。 #### 使用 Node.js 中的 Swagger Express 对于 Node.js 开发者来说,可以使用 Swagger Express 来集成 Swagger 功能。通过该工具,开发者能够轻松定义并生成实时更新的 Swagger 文档。具体实现方式可以通过官方文档进一步了解[^1]。 #### 针对 Ruby 应用程序的 swagger-blocks 如果目标环境是基于 Ruby 的应用程序,则可以选择 `swagger-blocks` 这一库来动态生成 Swagger JSON 文件。此项目的源码托管在 GitCode 上,提供了详细的入门指南以及如何将其应用于实际开发中的说明[^2]。 #### Spring Boot 下的 Swagger 实现案例 以下是利用 Swagger 提供的注解功能,在 Spring Boot 项目中创建简单 API 接口的一个例子: ```java import io.swagger.annotations.Api; import io.swagger.annotations.ApiOperation; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; @RestController @RequestMapping("/users") @Api(tags = "用户管理", description = "提供用户的增删改查操作") public class UserController { @ApiOperation(value = "获取用户列表", notes = "返回所有注册过的用户数据") @GetMapping("/list") public List<User> getUserList() { // 返回模拟的用户列表 return Arrays.asList(new User("Alice"), new User("Bob")); } } ``` 上述代码片段展示了如何运用 `@Api` 和 `@ApiOperation` 注解读取器来自动生成 API 描述信息[^3]^,^ [^4]。 --- ### 常见 Swagger 注解及其用途 为了更清晰地表达各个端点的功能与结构,Swagger 定义了一系列标准注解以便开发者标注其服务接口。下面列举了一些常用的注解形式及其作用范围: - **@Api**: 此标签通常放置在一个控制器类之上,用来指定当前模块所属领域或者主题分类。 - **tags 属性**: 表明分组标识符,方便前端页面按类别筛选展示不同区域下的方法集合。 - **description 字段**: 给定一段文字解释这个资源代表什么意义或业务逻辑背景。 这些基本概念构成了我们理解并实践 Swagger 的基础[^4]。
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值