swagger

最新推荐文章于 2024-06-17 20:10:54 发布

原创最新推荐文章于 2024-06-17 20:10:54 发布 · 228 阅读

0 ·

CC 4.0 BY-SA版权

文章标签：

#swagger #swagger2 #springboot #接口 #rest

swagger 专栏收录该内容

1 篇文章

订阅专栏

本文详细介绍Swagger框架，一种用于生成、描述、调用和可视化RESTful Web服务的强大工具。文章涵盖Swagger的基本概念、如何在SpringBoot项目中集成Swagger，包括依赖添加、配置类编写、控制器注解使用等关键步骤，以及Swagger提供的各种注解及其作用。

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

什么是swagger

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger让部署管理和使用功能强大的API变得非常简单。官方网站：http://swagger.io/。

springboot集成swagger

添加依赖（这里只列出swagger相关依赖）

		<!-- swagger -->
		<dependency>
		    <groupId>io.springfox</groupId>
		    <artifactId>springfox-swagger2</artifactId>
		    <version>2.2.2</version>
		</dependency>
		<dependency>
		    <groupId>io.springfox</groupId>
		    <artifactId>springfox-swagger-ui</artifactId>
		    <version>2.2.2</version>
		</dependency>

swagger配置类

@Configuration
@EnableSwagger2
public class SwaggerConfig {
     
    @Bean
    public Docket swaggerSpringMvcPlugin() {
        return new Docket(DocumentationType.SWAGGER_2).select().apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)).build();
    }
     
}

controller添加相关注解

@Api(description = "用户接口")
@RestController
public class LoginController {
	@ApiOperation(value="测试登录接口", notes="测试登录接口" ,httpMethod="POST")
	@RequestMapping("/login")
	@ResponseBody
	public String login(@ApiParam @RequestBody User user){
		Subject subject = SecurityUtils.getSubject();
		UsernamePasswordToken upt=new UsernamePasswordToken(user.getUsername(),user.getPassword());
		try {
			subject.login(upt);
			return "true";
		} catch (AuthenticationException e) {
			return "false";
		}
	}
}

swagger中相关的注解

@Api：用在请求的类上，表示对类的说明
    tags="说明该类的作用，可以在UI界面上看到的注解"
    value="该参数没什么意义，在UI界面上也看到，所以不需要配置"

@ApiOperation：用在请求的方法上，说明方法的用途、作用
    value="说明方法的用途、作用"
    notes="方法的备注说明"

@ApiImplicitParams：用在请求的方法上，表示一组参数说明
    @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
        name：参数名
        value：参数的汉字说明、解释
        required：参数是否必须传
        paramType：参数放在哪个地方
            · header --> 请求参数的获取：@RequestHeader
            · query --> 请求参数的获取：@RequestParam
            · path（用于restful接口）--> 请求参数的获取：@PathVariable
            · body（不常用）
            · form（不常用）    
        dataType：参数类型，默认String，其它值dataType="Integer"       
        defaultValue：参数的默认值

@ApiResponses：用在请求的方法上，表示一组响应
    @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
        code：数字，例如400
        message：信息，例如"请求参数没填好"
        response：抛出异常的类

@ApiModel：用于响应类上，表示一个返回响应数据的信息
            （这种一般用在post创建的时候，使用@RequestBody这样的场景，
            请求参数无法使用@ApiImplicitParam注解进行描述的时候）
    @ApiModelProperty：用在属性上，描述响应类的属性

详细解释参考 https://www.jianshu.com/p/f30e0c646c63