springboot+swagger2说明

最新推荐文章于 2025-04-04 11:21:47 发布

Ivan 000

最新推荐文章于 2025-04-04 11:21:47 发布

阅读量1.2w

点赞数 2

分类专栏： Spring 文章标签： springboot swagger s

本文链接：https://blog.csdn.net/fanpeng1100/article/details/54016292

版权

Spring 专栏收录该内容

1 篇文章

订阅专栏

本文介绍如何使用Swagger2为Spring Boot应用配置API文档，包括添加依赖、初始化配置及控制器示例。

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

swagger用于定义API文档。

优势：

前后端分离开发
API文档非常明确
测试的时候不需要再使用URL输入浏览器的方式来访问Controller
传统的输入URL的测试方式对于post请求的传参比较麻烦（当然，可以使用postman这样的浏览器插件

添加pom依赖

<!--swagger2 start-->
<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>
<!--swagger2 end-->

Swagger2Config初始化配置如下：

package com.gasq.travel.config;

import com.gasq.travel.common.CodeEnum;
import com.gasq.travel.utils.collections.ListUtils;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.context.request.async.DeferredResult;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.builders.ResponseMessageBuilder;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.ResponseMessage;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.List;

/**
 * @description: swagger2配置文件类
 * @访问路径： 如 http://localhost:8080/swagger-ui.html
 * @author fanpeng
 * @create 2017-01-03 10:00
 * @Modify By:
 **/
@Configuration
@EnableSwagger2
@ConfigurationProperties
public class Swagger2Config {
    @Value("${swagger.version}") private String version;
    @Value("${swagger.basePackage}") private String basePackage;

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("travel")
                .genericModelSubstitutes(DeferredResult.class)
                .useDefaultResponseMessages(false)
                .globalResponseMessage(RequestMethod.GET,customerResponseMessage())
                .forCodeGeneration(true)
                .select()
                .apis(RequestHandlerSelectors.basePackage(basePackage))
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("国安社区-travel接口")
                .description("I'm description..")
                .contact("东哥")
                .version(version)
                .license("国安社区")
                .licenseUrl("baidu.com")
                .build();
    }

    /**
     * 自定义返回信息
     * @param
     * @return
     */
    private List<ResponseMessage> customerResponseMessage(){
        return ListUtils.convertToList(
                new ResponseMessageBuilder()//500
                        .code(CodeEnum.error.getValue())
                        .message(CodeEnum.error.getDescription())
                        .responseModel(new ModelRef("Error"))
                        .build(),
                new ResponseMessageBuilder()//401
                        .code(CodeEnum.paramError.getValue())
                        .message(CodeEnum.paramError.getDescription())
                        .build());
    }


}

Controller中测试方法：

在这里我们使用@ApiOperation注解来声明此方法为要生成的接口文档，在配置中已经配置过了，如果不想方法生成文档，不加此注解即可；

配置中已经使用了自定义的响应信息，所以可以不设置@ApiResponses；

    @ApiOperation(value="测试日志程序", notes="测试日志程序", produces = "application/json")
    @ApiImplicitParams(value = {
            @ApiImplicitParam(name = "school", value = "学校名称", required = true, paramType = "query", dataType = "String"),
            @ApiImplicitParam(name = "name", value = "姓名", required = true, paramType = "query", dataType = "String")
    })
    @RequestMapping(value = "/get",method = RequestMethod.GET)
    public void testProgram(HttpServletRequest request, HttpServletResponse response){
        logger.debug("debug");
        logger.info("info");
        logger.error("error");
        logger.warn("warn");

        Student student = studentCommandService.selectById(1);
//        Student student = studentCommandService.queryById(1l);
        System.out.println(student.toString());
        this.renderJson(CodeEnum.success.getValue(),CodeEnum.success.getDescription(),student,request,response);
    }

注解说明：

@Api：用在类上，说明该类的作用
@ApiOperation：用在方法上，说明方法的作用
@ApiImplicitParams：用在方法上包含一组参数说明
@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
- paramType：参数放在哪个地方
  - header-->请求参数的获取：@RequestHeader
  - query-->请求参数的获取：@RequestParam
  - path（用于restful接口）-->请求参数的获取：@PathVariable
  - body（不常用）
  - form（不常用）
- name：参数名
- dataType：参数类型
- required：参数是否必须传
- value：参数的意思
- defaultValue：参数的默认值
@ApiResponses：用于表示一组响应
@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
- code：数字，例如400
- message：信息，例如"请求参数没填好"
- response：抛出异常的类
@ApiModel：描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）
- @ApiModelProperty：描述一个model的属性