0
0

SpringBoot——整合Swagger

Swagger

  • Swagger是一款基于RESTful接口的用于文档在线自动生成和功能测试的开发工具
  • 为了减少前后端开发人员在开发期间的频繁沟通，可以使用Swagger提供的接口文档和线上接口进行前后端功能联调（前端代码和后端代码可以独立开发，后端开发人员不必立即理解前端代码的实现细节****）
  • Swagger工具的功能： - 辅助接口设计- 辅助接口开发- 生成接口文档- 进行接口测试- Mock接口- 接口管理- 接口检测
  • Swagger可以整合到SpringBoot项目中并生成RESTful API文档，减少了开发者创建文档的工作量，同时将接口的说明内容整合在Java代码中，让维护文档和修改代码合为一体，可以让开发者在修改代码逻辑的同时方便地修改文档说明

Swagger工具集

  • Swagger-tools：提供各种与Swagger进行集成和交互的工具。例如模式检验、Swagger1.2文档转换成Swagger2.0文档等功能。
  • Swagger-core：用于Java/Scala的Swagger实现。与JAX-RS(Jersey、Resteasy、CXF…）、Servlets和Play框架进行集成。
  • Swagger-js：用于JavaScript的Swagger实现。
  • Swagger-node-express：Swagger模块，用于node.js的Express web应用框架。
  • Swagger-ui：一个无依赖的HTML、JS和CSS集合，可以为Swagger兼容API动态生成优雅文档。
  • Swagger-codegen：一个模板驱动引擎，通过分析用户Swagger资源声明以各种语言生成客户端代码

Swagger注解

  • @Configuration：表明这是一个配置类
  • @EnableSwagger2：开启Swagger2
  • @Api：放在类上，描述一个类的基本信息。
  • @ApiOperation：放在方法上，描述一个方法的基本信息 - value：对方法作用的一个简短描述- notes：用来备注该方法的详细作用
  • @ApiImplicitParams：用在方法上，包含一组参数说明
  • @ApiImplicitParam：用来注解来给方法入参增加说明，一个请求能数 - paramType：指方法参数的类型，可选值如下 - path，参数获取方式：@PathVariable- query，参数获取方式：@RequestParam- header，参数获取方式：@RequestHeader- body- form- name：参数名称，和参数变量相对应- value：参数的描述信息- required：该字段是否必填- defaultValue：该字段的默认值
  • @ApiResponses：用于表示一组响应。
  • @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息 - code：响应码- message：描述信息，例如“请求参数没填好”- response：抛出异常的类
  • @ApiModel：用对象来接收参数，描述一个Model的信息（一般用于在请求参数无法使用@ApiImplicitParam注解进行描述的时候）
  • @ApiModelProperty：用对象接收参数时，描述对象的一个字段
  • @ApiIgnore：不对某个接口生成文档
  • @ApiError ：发生错误返回的信息

项目总结

SpringBoot整合Swagger：

  1. 引入pom的相关依赖
  2. 在代码中加入相应的配置，新建config包，写入swaggerConfig配置类
  3. 在basePackage指定的路径下使用swagger（使用api注解，编写控制器类）
  4. 启动项目，浏览器打开http://ip:port/swagger-ui.html进行测试

新建SpringBoot项目

项目结构：

pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.3.12.RELEASE</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>
    <groupId>com.study</groupId>
    <artifactId>springboot_swagger</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>springboot_swagger</name>
    <description>Demo project for Spring Boot</description>
    <properties>
        <java.version>8</java.version>
    </properties>
    <dependencies>

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

        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>

</project>

Swagger2Config配置类

package com.study.springboot_swagger.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 //启用Swagger API文档
public class Swagger2Config {

    /**
     * 返回实例Docket(Swagger API摘要)
     * 在方法中指定扫描的控制器包路径,
     * 只有在此路径下的Controller类才会自动生成Swagger API文档
     * @return
     */
    @Bean
    public Docket api(){
        return new Docket(DocumentationType.SWAGGER_2)  // 指定 Swagger 的版本为 2
                .apiInfo(apiInfo())  // 设定 API 文档的基本信息
                .select()  // 进入 API 选择模式
                .apis(RequestHandlerSelectors.basePackage("com.study.springboot_swagger.controller"))  // 指定扫描的包路径，Swagger 将扫描该包下的所有 Controller 类
                .paths(PathSelectors.any())  // 指定要包含的路径，PathSelectors.any() 表示包括所有路径
                .build();  // 完成 Docket 实例的构建
    }

    /**
     * 配置一些基本的显示信息,
     * 比如标题,描述,版本,服务条款,联系方式等
     * @return
     */
    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("swagger-api文档")
                .description("swagger 文档 by liufu")
                .version("1.0")
                .build();
    }
}

User实体类

package com.study.springboot_swagger.entity;

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

@ApiModel(value = "用户实体类", description = "用户信息描述类")
@Data //getter,setter方法
public class User{
    @ApiModelProperty(value = "用户名")
    private String username;

    @ApiModelProperty(value = "用户地址")
    private String address;
}

UserController控制器

package com.study.springboot_swagger.controller;

import com.study.springboot_swagger.entity.User;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.*;
import springfox.documentation.annotations.ApiIgnore;

@RestController
@Api(tags = "用户数据接口")
public class UserController {

    @ApiOperation(value = "查询用户", notes = "根据id查询用户")
    @ApiImplicitParam(paramType = "path", name = "id", value = "用户id", required = true)
    @GetMapping("/user/{id}")
    public String getUserById(@PathVariable Integer id){
        return "/user/"+id;
    }

    @ApiResponses({
            @ApiResponse(code = 200, message = "删除成功!"),
            @ApiResponse(code = 500, message = "删除失败!")
    })
    @ApiOperation(value = "删除用户", notes = "通过id删除用户")
    @DeleteMapping("/user/{id}")
    public Integer deleteUserById(@PathVariable Integer id){
        return id;
    }

    @ApiOperation(value = "添加用户", notes = "添加一个用户,传入用户名和地址")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType = "query", name = "username", value = "用户名", required = true, defaultValue = "sang"),
            @ApiImplicitParam(paramType = "query", name = "address", value = "用户地址", required = true, defaultValue = "shenzhen")
    })
    @PostMapping("/user")
    public String addUser(@RequestParam String username, @RequestParam String address){
        return username + ":" + address;
    }

    @ApiOperation(value = "修改用户", notes = "修改用户,传入用户信息")
    @PutMapping("/user")
    public String updateUser(@RequestBody User user){
        return user.toString();
    }

    @GetMapping("/ignore")
    @ApiIgnore
    public void ignoreMethod(){

    }
}

项目测试

访问网址：http://localhost:8080/swagger-ui.html，查看接口文档

展开一个接口描述，单击Try it out ，在Parameters区域填写信息，点击 Execute 进行接口测试，Responses区域为测试结果

添加用户

修改用户

查询用户

删除用户

标签： spring boot 后端 java
本文转载自: https://blog.csdn.net/weixin_72052233/article/details/141277304
版权归原作者 戏拈秃笔 所有， 如有侵权，请联系我们删除。
登录后发布评论

“SpringBoot——整合Swagger”的评论:

还没有评论
关于作者
...
overfit同步小助手
文章同步
相关阅读

落实算法安全主体责任：全面保障算法合规与安全

Hadoop生态圈框架部署（四）- Hadoop完全分布式部署

毕设项目 基于大数据的b站数据分析

【前端】Bootstrap：栅格系统 (Grid System)

docker部署rustdesk

【PostgreSQL】实战篇——用户管理、角色和权限控制的高级用法及技巧

AI时代：弯道超车的新思维与实践路径

文章导航