当前位置：首页 > news >正文

SpringBoot+Swagger详细使用方法

news 2025/9/7 21:10:51

一、接口文档概述

swagger是当下比较流行的实时接口文文档生成工具。接口文档是当前前后端分离项目中必不可少的工具，在前后端开发之前，后端要先出接口文档，前端根据接口文档来进行项目的开发，双方开发结束后在进行联调测试。

二、常用注解

- @Api()用于类；（controller） 
表示标识这个类是swagger的资源
- @ApiOperation()用于方法； 
表示一个http请求的操作 
- @ApiParam()用于方法，参数，字段说明； 
表示对参数的添加元数据（说明或是否必填等） 
- @ApiModel()用于类 主要是用于接受对象的信息
表示对类进行说明，用于参数用实体类接收 
- @ApiModelProperty()用于方法，字段 
表示对model属性的说明或者数据操作更改 
- @ApiIgnore()用于类，方法，方法参数 
表示这个方法或者类被忽略 
- @ApiImplicitParam() 用于方法 
表示单独的请求参数 
- @ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam
-@ApiResponse() 用于方法
对返回响应头的说明
-@ApiResponses用于方法，包含多个@ApiResponse

三、pom依赖

1、在pom.xml文件中添加swagger相关依赖

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

第一个是API获取的包，第二是官方给出的一个ui界面。这个界面可以自定义，默认是官方的，对于安全问题，以及ui路由设置需要着重思考。

package com.aaa.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
public class Swagger2 {@Beanpublic Docket createRestApi() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.basePackage("com.aaa.controller")).paths(PathSelectors.any()).build();}private ApiInfo apiInfo() {return new ApiInfoBuilder().title("服务:发布为daocke镜像,权限管理，用户管理，页面管理，日志 后台 APIs").description("服务:发布为daocke镜像,权限管理，用户管理，页面管理，日志 后台").termsOfServiceUrl("http://192.168.1.198:10070/platformgroup/ms-admin") //代码的路径.contact("小宇").version("1.0").build();}}

springboot版本比较高的时候可能会和swagger出现版本不兼容的问题想要解决这个问题可以在
application文件中加上:

spring.mvc.pathmatch.matching-strategy=ant_path_matcher

四、在controller中的使用

主要用于在API上做一些声明

package com.aniu.test1.controller;import com.aniu.test1.entity.User;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.*;@Api(tags = "用户管理")
@RestController
public class UserController {@ApiOperation("添加用户")@PostMapping("/add")public User add(@ApiParam("用户") User user){return new User();}@ApiOperation("修改用户")@PostMapping("/update")public String update() {return "修改";}@ApiOperation("删除用户")@GetMapping("/delete")public boolean delete(@ApiParam("用户编号") Integer id) {return true;}@ApiOperation("查询用户")@GetMapping("/query")@ApiResponses(value = { @ApiResponse(code = 1000, message = "成功"), @ApiResponse(code = 1001, message = "失败"),@ApiResponse(code = 1002,message = "缺少参数") })@ApiImplicitParams({@ApiImplicitParam(name = "name", value = "电影名", dataType = "String", paramType = "query", required = true),})public User query(@RequestParam String name) {User user = new User();user.setUserName("name");user.setPassword("password");return  user;}
}

访问路径：http://localhost:8080/swagger-ui.html

五、使用bootstrap的ui

现已更名knife4j
https://doc.xiaominfo.com/docs/action/springboot

<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.7.0</version></dependency><dependency><groupId>com.github.xiaoymin</groupId><artifactId>swagger-bootstrap-ui</artifactId><version>1.9.6</version>
</dependency>