springboot+swagger2

时间：2024-07-10 08:36:20

springboot+swagger2

小序

新公司的第二个项目，是一个配置管理终端机(比如:自动售卖机，银行取款机)的web项目，之前写过一个分模块的springboot框架，就在那个框架基础上进行了改造。改造后的框架可以说能满足普通项目的所有需求，大家可以循环利用哈。后续我会附上摘出来的框架源码，和大家一起学习进步。今天主要是说一下springboot配置在线接口文档swagger2。

添加jar

在你的maven管理的项目的pom.xml中添加

 <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的配置类

 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;

 /**

  * Swagger2配置类 在与spring boot集成时，放在与Application.java同级的目录下。

  * 通过@Configuration注解，让Spring来加载该类配置。 再通过@EnableSwagger2注解来启用Swagger2。

  */

 @Configuration

 @EnableSwagger2

 public class Swagger2 {

     /**

      * 创建API应用 apiInfo() 增加API相关信息

      * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，

      * 本例采用指定扫描的包路径来定义指定要建立API的目录。

      *

      * @return

      */

     @Bean

     public Docket createRestApi() {

         return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()

                 .apis(RequestHandlerSelectors.basePackage("com.11.22.33.controller"))//此处改为你的接口所在的包路径

                 .paths(PathSelectors.any()).build();

     }

     /**

      * 创建该API的基本信息（这些基本信息会展现在文档页面中） 访问地址：http://项目实际地址/swagger-ui.html

      *

      * @return

      */

     private ApiInfo apiInfo() {

         return new ApiInfoBuilder().title("title").description("description").contact("作者")

                 .version("1.0").build();//此处改为你自己的项目名称，描述，作者，版本

     }

 }

controller添加swagger2注解

  • 例一

多个参数的话，添加多个@ApiImplicitParam即可，逗号分隔。

import io.swagger.annotations.Api;

import io.swagger.annotations.ApiImplicitParam;

import io.swagger.annotations.ApiImplicitParams;

import io.swagger.annotations.ApiOperation;

@Api(value = "DeviceProductController|终端设备下的产品的相关接口")

@RequestMapping(RequestUrl.DEVEICE_PRODUCT_LIST)

@RestController

public class DeviceProductController {

    @Autowired

    private DeviceProductService deviceProductService;

    @ApiOperation(value="根据设备编号获取产品列表")

    @ApiImplicitParams({

        @ApiImplicitParam(paramType="query", name = "deviceId", value = "设备编号", required = true, dataType = "String")

    })

    @RequestMapping(method = RequestMethod.GET)

    String deveiceInfos(String  deviceId, HttpServletRequest request) {

        String result = deviceProductService.getDeviceProductList(deviceId);

        return result;

    }

}

springboot+swagger2

  • 例二

import io.swagger.annotations.Api;

import io.swagger.annotations.ApiImplicitParam;

import io.swagger.annotations.ApiImplicitParams;

import io.swagger.annotations.ApiOperation;

@Api(value = "DeviceInfoController|终端设备的相关接口")

@RequestMapping(RequestUrl.DEVEICE_INFO_LIST)

@RestController

public class DeviceInfoController {

    @Autowired

    private DeviceInfoService deveiceInfoService;

    @ApiOperation(value="分页获取终端列表datatable的数据格式")

    @RequestMapping(method = RequestMethod.GET)

    String deveiceInfos(@ModelAttribute Gpage page, HttpServletRequest request) {

        String result = deveiceInfoService.deveiceInfos(page, request);

        return result;

    }

}
import io.swagger.annotations.ApiModel;

import io.swagger.annotations.ApiModelProperty;

import lombok.Data;

@ApiModel(value="分页对象类型")

@Data

public class Gpage{

    @ApiModelProperty(value="每页显示个数" ,required=true)

    private int length = 10;

    @ApiModelProperty(value="开始坐标" ,required=true)

    private int start;

}

springboot+swagger2

在线接口文档访问路径

我本地启用的是8081端口，所以访问路径是http://localhost:8081/swagger-ui.html

遇到的坑

  • 如果你配置了spring.resources.static-locations,那你就需要把swagger-ui.html也要加进去

解决办法：新建类MyWebAppConfigurer,添加如下代码即可

 import org.springframework.context.annotation.Configuration;

 import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;

 import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;

 @Configuration

 public class MyWebAppConfigurer extends WebMvcConfigurerAdapter {

     /**

      * 添加swagger-ui.html

      */

     @Override

     public void addResourceHandlers(ResourceHandlerRegistry registry) {

          registry.addResourceHandler("swagger-ui.html")

          .addResourceLocations("classpath:/META-INF/resources/");

          registry.addResourceHandler("/webjars*")

          .addResourceLocations("classpath:/META-INF/resources/webjars/");

         super.addResourceHandlers(registry);

     }

 }
  • 如果你配置了拦截器或者过滤器，也要过滤掉swagger的相关路径

相关文章