Swagger学习


推荐导航

0.系统学习导航传送
>注解介绍
>替换ui界面参考地址


一.概述

文档向来在软件开发过程中的每一个阶段都是非常重要的,如果没有文档,那软件的可维护性就会变得很糟,以致于影响可扩展性,最后慢慢的使软件变成一堆乱糟糟的无用的代码。而不同系统之间的接口文档其重要性更显而易见,一般常用的接口文档采用以下形式:

  • 口口相传
  • 用world或其他文本文件进行保存
  • 用wiki编写
    上面这些方式都有各自的缺点,比如不易维护,不易测试接口,接口变更而文档未能同步更新等。但Swagger的出现改变了这些情形,Swagger的文档编写相当于就是在写代码,在更改接口代码的同时就能方便的更新文档,还能方便的进行接口的测试。

二.入门案例

  1. 先创建号springboot的web项目 (详细见springboot的入门)

  2. 导入swagger的jar

    <!-- swagger2 api文档 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>
  1. 编写配置

@Configuration
@EnableSwagger2
public class SwaggerConfig {
     @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .pathMapping("/")
                .groupName("RestApi")   //组
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.ganyz.springcloudproducer.controller"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(new ApiInfoBuilder()
                        .title("springboot 整合 swagger")//接口文档的标题
                        .description("springboot 整合 swagger test")
                        .version("test 01")
                        .contact(new Contact("name", "url", "email"))    // 开发文档的作者信息
                        .license("license") //license 规范
                        .licenseUrl("licenseUrl")
                        .build());
    }

	// Docket:如果需要分组显示不同文件夹下的controller,则写多个, 否则只需要写上面一个Docket就好了
    @Bean
    public Docket createRestCopyApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .pathMapping("/")
                .groupName("RestCopyApi")//组
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.ganyz.springcloudproducer.controllerCopy"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(new ApiInfoBuilder()
                        .title("springboot 整合 swagger")//接口文档的标题
                        .description("springboot 整合 swagger test")
                        .version("test 01")
                        .contact(new Contact("name", "url", "email"))    // 开发文档的作者信息
                        .license("license") //license 规范
                        .licenseUrl("licenseUrl")
                        .build());
    }
}

4.书写controller

package com.ganyz.springcloudproducer.controller;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.ResponseBody;
/**
 * @date 2021/5/11
 */
@Api(tags = "用户服务接口swagger")
@Controller
@RequestMapping("swagger2All")
public class SwaggerHelloWorldController {
    @ApiOperation(value = "查询:swagger", notes = "查询swagger的接口")      // value: 请求路径后面的解释;
    @RequestMapping("/swagger")
    @ResponseBody
    public String swagger(){
        System.out.println("swagger=====");
        return "swagger";
    }
}

@Controller
public class HelloWorldController {
    @RequestMapping("/hello")
    @ResponseBody
    public String hello(){
        System.out.println("hello=====");
        return "hello";
    }
}
  1. 请求页面地址

地址:http://localhost:10212/swagger-ui
>
在这里插入图片描述

三.注释介绍

  • @Api() 用在请求的类上,表示对类的说明,也代表了这个类是swagger2的资源

tags:说明该类的作用,参数是个数组,可以填多个。
value=“该参数没什么意义,在UI界面上不显示,所以不用配置”
description = “用户基本信息操作”


  • @ApiOperation():用于方法,表示一个http请求访问该方法的操作

value=“方法的用途和作用”
notes=“方法的注意事项和备注”
tags:说明该方法的作用,参数是个数组,可以填多个。
格式:tags={“作用1”,“作用2”}
(在这里建议不使用这个参数,会使界面看上去有点乱,前两个常用)


  • @ApiModel():用于响应实体类上,用于说明实体作用

description=“描述实体的作用”


  • @ApiModelProperty() 用在属性上,描述实体类的属性

value=“用户名” 描述参数的意义
name=“name” 参数的变量名
required=true 参数是否必选


四.swagger替换ui界面

  • 关于spring boots中使用swagger-bootstrap-ui 替换默认ui, 导入如下jar

        <!-- swagger2 api文档 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>
        <!-- spring boots中使用swagger-bootstrap-ui -->

        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.8.3</version>
        </dependency>

访问地址: http://localhost:10212/doc.html

在这里插入图片描述

### 关于 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]。
评论 1
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

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

抵扣说明:

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

余额充值