文章详情

短信预约-IT技能 免费直播动态提醒

请输入下面的图形验证码

提交验证

短信预约提醒成功

Spring Boot中如何使用Swagger详解

2024-04-02 19:55

关注

Swagger 简介

Swagger 是一个方便 API 开发的框架,它有以下优点:

配置 Swagger

Swagger 目前有 2.x 和 3.x 两个主流版本,配置略有不同。

添加依赖

首先去 Maven 仓库中搜索 springfox 查找依赖的坐标,Swagger 是遵循 OpenAPI 规范的技术,而 springfox 是该技术的一种实现,所以这里要搜 springfox 而不是 swagger。

对于 Swagger 2.x,需要在 pom.xml 中添加两项配置:


<!-- 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>

对于 Swagger 3.x,简化了配置项,只需要在 pom.xml 中添加一项配置:


<!-- https://mvnrepository.com/artifact/io.springfox/springfox-boot-starter -->
<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-boot-starter</artifactId>
  <version>3.0.0</version>
</dependency>

为项目开启 Swagger

对于 Swagger 2.x,使用 @EnableSwagger2 注解开启 Swagger 功能。


@EnableSwagger2
@SpringBootApplication
public class SwaggerApplication {
    ...
}

对于 Swagger 3.x,使用 @EnableOpenApi 注解开启 Swagger 功能。


@EnableOpenApi
@SpringBootApplication
public class SwaggerApplication {
    ...
}

创建 SwaggerConfig 配置类

下面是一份配置模板:


import org.springframework.beans.factory.annotation.Value;
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.*;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
public class SwaggerConfig {

    @Value("${spring.profiles.active:NA}")
    private String active;

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)  // OAS_30
                .enable("dev".equals(active))  // 仅在开发环境开启Swagger
                .apiInfo(apiInfo())
                .host("http://www.example.com")  // Base URL
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("API文档")
                .description("这是描述信息")
                .contact(new Contact("张三", null, null))
                .version("1.0")
                .build();
    }
}

访问 Swagger 前端页面

控制器相关注解

@Api:将一个类标记为 Swagger 资源,一般放在 Controller 类上面,通过 tags 指定描述信息,比如 @Api(tags="用户管理")。

@ApiOperation:本注解放在 Controller 方法上面,描述该方法的作用。

@ApiParam:本注解放在 Controller 方法的形参前面,可以描述参数的作用,比如 @ApiParam("用户名") String username。可以使用 value 指定描述信息,通过 required = true 指定必需传递该参数。


package com.example.swagger.controller;

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.RestController;

@Api(tags = "Hello控制器")
@RestController
public class HelloController {
    @ApiOperation("展示欢迎信息")
    @GetMapping("/hello")
    public String hello(@ApiParam("名字") String name) {
        return "hello, " + name;
    }
}

实体相关注解

![](cdn.jsdelivr.net/gh/jpch89/P… 在 Spring Boot 中使用 Swagger 00.png)
如果仅仅想指定描述,而不改变原始类名显示,可以写成 @ApiModel(description = "用户")。


package com.example.swagger.pojo;

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

@Data
@ApiModel(description = "用户")
public class User {
    @ApiModelProperty("用户名")
    private String username;
    @ApiModelProperty("密码")
    private String password;
    @ApiModelProperty(value = "年龄", example = "18", required = true)
    private int age;
    @ApiModelProperty(hidden = true)
    private double money;
}

总结

到此这篇关于Spring Boot中如何使用Swagger的文章就介绍到这了,更多相关SpringBoot使用Swagger内容请搜索编程网以前的文章或继续浏览下面的相关文章希望大家以后多多支持编程网!

阅读原文内容投诉

免责声明:

① 本站未注明“稿件来源”的信息均来自网络整理。其文字、图片和音视频稿件的所属权归原作者所有。本站收集整理出于非商业性的教育和科研之目的,并不意味着本站赞同其观点或证实其内容的真实性。仅作为临时的测试数据,供内部测试之用。本站并未授权任何人以任何方式主动获取本站任何信息。

② 本站未注明“稿件来源”的临时测试数据将在测试完成后最终做删除处理。有问题或投稿请发送至: 邮箱/279061341@qq.com QQ/279061341

软考中级精品资料免费领

  • 历年真题答案解析
  • 备考技巧名师总结
  • 高频考点精准押题
  • 2024年上半年信息系统项目管理师第二批次真题及答案解析(完整版)

    难度     813人已做
    查看
  • 【考后总结】2024年5月26日信息系统项目管理师第2批次考情分析

    难度     354人已做
    查看
  • 【考后总结】2024年5月25日信息系统项目管理师第1批次考情分析

    难度     318人已做
    查看
  • 2024年上半年软考高项第一、二批次真题考点汇总(完整版)

    难度     435人已做
    查看
  • 2024年上半年系统架构设计师考试综合知识真题

    难度     224人已做
    查看

相关文章

发现更多好内容

猜你喜欢

AI推送时光机
位置:首页-资讯-后端开发
咦!没有更多了?去看看其它编程学习网 内容吧
首页课程
资料下载
问答资讯