SpringBoot集成Swagger接口文档

最新推荐文章于 2024-07-31 09:32:30 发布

原创最新推荐文章于 2024-07-31 09:32:30 发布 · 252 阅读

0 ·

CC 4.0 BY-SA版权

文章标签：

#swagger

java 同时被 2 个专栏收录

19 篇文章

订阅专栏

springBoot

14 篇文章

订阅专栏

本文详细介绍如何在Spring Boot项目中集成Swagger2，包括Maven依赖添加、配置类编写、Controller注解使用及参数文档配置，助您快速上手API文档自动生成。

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

一、引入maven

<!-- swagger ui -->
        <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对应2.0的springboot版本，假如用高版本的Springboot则同样要引用高版本的swagger！
二、配置类

/**
 * @author wy
 * @date 2020/08/21
 * @time 14:51
 * @desc Swagger配置类
 * 等
 */
@Configuration
@EnableSwagger2//开启swagger2功能
public class SwaggerConfig {
    /**
     * 创建API应用
     * apiInfo() 增加API相关信息
     * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，
     * 本例采用指定扫描的包路径来定义指定要建立API的目录。
     *
     * @return
     */
    @Bean
    public Docket createRestApi(){
        //版本类型是swagger2
        return new Docket(DocumentationType.SWAGGER_2)
                //通过调用自定义方法apiInfo，获得文档的主要信息
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com"))//扫描该包下面的API注解
                .paths(PathSelectors.any())
                .build();
    }
    /**
     * 创建该API的基本信息（这些基本信息会展现在文档页面中）
     * 访问地址：http://项目实际地址/swagger-ui.html
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Swagger2接口文档") //接口管理文档首页显示
                .description("Swagger使用演示")//API的描述
                .termsOfServiceUrl("www1")//网站url等
                .version("1.0")
                .build();
    }
}

三、配置Controller

@Controller
@RequestMapping("/test")
@Api("测试controller")
public class AdminController {

    @ResponseBody
    @PostMapping("/msg")
    @ApiOperation("查询操作")
    public TestResponse getMsg(@RequestBody TestRequest request){
        TestResponse re = new TestResponse();
        re.setAge(10);
        re.setName(request.getName());
        return re;
    }
}

效果图：
在这里插入图片描述
@Api(“测试controller”) //代表swagger注解，用在类上
@ApiOperation(“查询操作”) //swagger注解，标识当前接口用途用在方法上
四、配置入参和出参swagger文档

@ApiModel("相应类")
public class TestResponse {
    @ApiModelProperty(value = "名称")
    private String name;
    @ApiModelProperty(value="年龄")
    private int age;

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public int getAge() {
        return age;
    }

    public void setAge(int age) {
        this.age = age;
    }
}

@ApiModel("请求类")
public class TestRequest {
    @ApiModelProperty(value = "名称")
    private String name;

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }
}