使用Swagger2构建RESTful API文档-CSDN博客

本文链接：https://blog.csdn.net/weixin_54966486/article/details/124700076

该博客介绍了如何使用Swagger2为Java后端API创建详细的文档。通过在控制器和方法上添加注解，如@Api和@ApiOperation，可以自动生成接口说明。同时，配置类中设置扫描的包路径并定制全局参数，以便在Swagger UI中展示和测试API。此外，还提到了相关依赖项的引入。

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

访问地址

http://后端服务器地址:端口号/swagger-ui.html

注解

控制类： @Api(tags = "...控制器")
方法上： @ApiOperation("分页带条件查询管理员信息 ")
变量上：	@ApiParam("JSON格式的Admin对象") String str

示例

@Api(tags = "其他业务（登录...）控制器")
.....
public class SystemController {

    //修改个人密码
    @ApiOperation("修改个人密码")
    @PostMapping("/updatePwd/{oldPwd}/{newPwd}")
    public Result updatePwd( 
	    @ApiParam("用户身份令牌") @RequestHeader("token") String token, 
	    @ApiParam("旧密码") @PathVariable("oldPwd") String oldPwd, 
	    @ApiParam("新密码") @PathVariable("newPwd") String newPwd)
    {
        ......
    }

配置类，修改要扫描注解的包路径

package com.xsmjz.smartCampus.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import java.util.ArrayList;
import java.util.List;

/**
 * Swagger2配置信息
 */
@Configuration
@EnableSwagger2
public class Swagger2Config {

    @Bean
    public Docket webApiConfig(){

        //添加head参数start
        List<Parameter> pars = new ArrayList<>();
        ParameterBuilder tokenPar = new ParameterBuilder();
        tokenPar.name("userId")
                .description("用户ID")
                .defaultValue("1")
                .modelRef(new ModelRef("string"))
                .parameterType("header")
                .required(false)
                .build();
        pars.add(tokenPar.build());

        ParameterBuilder tmpPar = new ParameterBuilder();
        tmpPar.name("userTempId")
                .description("临时用户ID")
                .defaultValue("1")
                .modelRef(new ModelRef("string"))
                .parameterType("header")
                .required(false)
                .build();
        pars.add(tmpPar.build());
        //添加head参数end

        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("webApi")
                .apiInfo(webApiInfo())
                .select()
                //可以测试请求头中：输入token
//                .apis(RequestHandlerSelectors.withClassAnnotation(ApiOperation.class))
                
               看这里修改要扫描注解的包路径
               .apis(RequestHandlerSelectors.basePackage("com.xsmjz.smartCampus.controller"))
                //过滤掉admin路径下的所有页面
                //.paths(Predicates.and(PathSelectors.regex("/sms/.*")))
                //过滤掉所有error或error.*页面
                //.paths(Predicates.not(PathSelectors.regex("/error.*")))
                .build()
                .globalOperationParameters(pars);

    }



    private ApiInfo webApiInfo(){

        return new ApiInfoBuilder()
                .title("网站-API文档")
                .description("本文档描述了网站微服务接口定义")
                .version("1.0")
                .contact(new Contact("atguigu", "http://atguigu.com", "512111559@qq.com"))
                .build();
    }

    private ApiInfo adminApiInfo(){

        return new ApiInfoBuilder()
                .title("后台管理系统-API文档")
                .description("本文档描述了后台管理系统微服务接口定义")
                .version("1.0")
                .contact(new Contact("atguigu", "http://atguigu.com", "512111559@qq.com"))
                .build();
    }


}

引入依赖

<!--swagger-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.7.0</version>
        </dependency>
        <!--swagger ui-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.7.0</version>
        </dependency>
        <!--swagger2  增强版接口文档-->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>2.0.4</version>
        </dependency>