springboot集成Swagger 3.0

最新推荐文章于 2024-08-20 17:25:50 发布

MR.阳阳

最新推荐文章于 2024-08-20 17:25:50 发布

阅读量1.6k

点赞数 3

本文链接：https://blog.youkuaiyun.com/weixin_38294968/article/details/126823288

版权

本文介绍了如何在SpringBoot项目中集成Swagger 3.0，包括添加依赖、启用Swagger、配置接口文档以及常用注解的使用。通过实例演示了如何为API和参数提供详细说明，帮助开发者更好地理解和使用Swagger进行接口文档生成和测试。

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

Swagger介绍

Swagger 是一个用于生成、描述和调用 RESTful 接口的 Web 服务。通俗的来讲，Swagger 就是将项目中所有（想要暴露的）接口展现在页面上，并且可以进行接口调用和测试的服务。

添加依赖

			<dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-boot-starter</artifactId>
                <version>3.0.0</version>
            </dependency>

开启swagger

在springboot的启动类型添加注解 @EnableOpenApi

@SpringBootApplication
@EnableOpenApi
public class ProjectTestUserApplication {

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

}

配置

package com.example.user.Utils;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.stereotype.Component;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.user.controller"))
                .build();
    }
}

访问swagger

直接访问http://ip:端口/swagger-ui/

swagger 常用注解

@Api 类注解,在控制类添加此注解,可以对控制器类进行功能说明
@ApiOperation 方法注解：说明接口方法的作用
@ApiImplicitParams和@ApiImplicitParam 在 Rest 接口方法上使用来指定请求参数
@ApiParam 是注解api的参数，用于swagger提供开发者文档，文档中生成的注释内容

@RequestMapping("/userController")
@RestController
@Api(value = "用户")
public class UserController {

    @Autowired
    private UserFeign userFeign;

    /**
     * 获取参数
     * @return
     */
    @ApiOperation(value = "查询用户")
    @ApiImplicitParams({
            @ApiImplicitParam(dataType = "string",name = "name",value = "用户名")
    })
    @GetMapping("userShow")
    public List<UserCommon> userShow(@ApiParam(value = "用户名",required = true) @RequestBody UserVo userCommon){
        return  userFeign.show();
    }
}

@ApiIgnore 可以用在类、方法上，方法参数中，用来屏蔽某些接口或参数，使其不在页面上显示。
@ApiModel 类注解,在返回和参数实体类添加此注解,可以对返回和参数实体类进行说明
@ApiModelProperty 参数注解

@ApiModel("用户vo")
@Data
public class UserVo {

    private int id;

    @ApiModelProperty(value = "编号")
    private String  name;

    @ApiModelProperty(value = "年龄")
    private int age;
}