关于swagger文档的使用方法

最新推荐文章于 2025-10-26 21:31:27 发布

原创最新推荐文章于 2025-10-26 21:31:27 发布 · 850 阅读

3 ·

CC 4.0 BY-SA版权

本文详细介绍如何在SpringBoot项目中集成Swagger2，包括引入依赖、配置类编写及接口注解使用等内容，帮助开发者快速掌握Swagger2的配置与应用。

引言

最近在后台开发的时候，使用swagger2进行前后台接口文档的声明。由此遇见的一些问题，写下来给自己复习。

参考：

https://blog.youkuaiyun.com/xupeng874395012/article/details/68946676

正文

在进行整合swagger2的时候，首先引入swagger2的jar，由于我使用的是springboot，所以以springboot为例。

<!--springboot 集成 swagger-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.5.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.5.0</version>
</dependency>

引入swagger2的jar包之后，我们需要配置一个swagger2的配置类，来声明一些swagger2的配置信息

这样的话，swagger2就已经配置完毕了。接下来你只需要在你的接口上配置你想要显示的信息即可。
 

@Configuration  //表示是配置类，要被加载
@EnableSwagger2 //swagger的配置
public class Swagger2 {

    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))  //添加ApiOperiation注解的被扫描
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo(){
        Contact contact = new Contact("xx", "www.baidu.com", "xxx@126.com");
        return new ApiInfoBuilder()
                .title("cc").contact(contact).description("接口文档").license("Apache License Version 2.0")
                .version("v1.0").build();
    }
}

接口上信息的配置如下：

@RestController
@Api(value = "user",  tags = "用户模块")
@RequestMapping("user")
public class UserController extends BaseController {

    @Resource
    private UserService userService;

    @ApiOperation(value = "用户添加")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "user",value = "用户" ,required = true,dataType = "String", paramType = "body")
    })
    @RequestMapping(value = "addUser",method = RequestMethod.POST)
    public ResultBean addUser(User user){
        return  resultBean;
    }
}

关于其中@Api和@ApiOperation等的详细解释如下：

作用范围	API	使用位置
对象属性	@ApiModelProperty	用于出入参数对象的字段上
协议集描述	@Api	用于Controller类上
协议描述	@ApiOperation	用在Controller的方法上
Response集	@ApiResponses	用在controller的方法上
Response	@ApiResponse	用在 @ApiResponses里边
非对象参数集	@ApiImplicitParams	用在controller的方法上
非对象参数描述	@ApiImplicitParam	用在@ApiImplicitParams的方法里边
描述返回对象的意义	@ApiModel	用在返回对象类上

关于参数的详细解释

属性	取值	作用
paramType		查询参数类型
	path	以地址的形式提交数据
	query	直接跟参数完成自动映射赋值
	body	以流的形式提交仅支持POST
	header	参数在request headers 里边提交
	form	以form表单的形式提交仅支持POST
dataType		参数的数据类型只作为标志说明，并没有实际验证
	Long
	String
name		接收参数名（必须与方法中参数名一致）
value		接收参数的意义描述（描述信息）
required		参数是否必填
	true	必填
	false	非必填
defaultValue		默认值