使用springfox整合Springboot和Swagger

叁歲伎倆 2022-06-02 12:09 150阅读 0赞

Swagger 是一系列对 RESTful 接口进行规范描述和页面展示的工具. 通过 springfox-swagger 将 Swagger 与 Spring-MVC 整合, 可从代码中的注解获取信息, 并生成相应的文档. 效果如下所示.

![SouthEast][]

下面开始集成：

首先导入依赖：

<dependency>
    			<groupId>io.springfox</groupId>
    			<artifactId>springfox-swagger2</artifactId>
    			<version>2.6.1</version>
    		</dependency>
    	    <dependency>
            	<groupId>io.springfox</groupId>
            	<artifactId>springfox-swagger-ui</artifactId>
            	<version>2.6.1</version>
            </dependency>

然后开启swagger配置：

package com.bigdata.lab.ymlib.config;
    
    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;
    
    /**
     * REST API UI
     * @author 
     * @update 2017年10月27日 下午12:02:07
     */
    @Configuration
    @EnableSwagger2
    public class SwaggerConfig {
      @Bean
      public Docket createRestApi() {
          return new Docket(DocumentationType.SWAGGER_2)
                  .apiInfo(apiInfo())
                  .select()
                  .apis(RequestHandlerSelectors.basePackage("com.bigdata.lab.ymlib.rest"))
                  .paths(PathSelectors.any())
                  .build();
      }
    
      private ApiInfo apiInfo() {
          return new ApiInfoBuilder()
                  .title("xxxx")
                  .description("xxxx")
                  .termsOfServiceUrl("xxxx")
                  .contact("xxxx")
                  .version("1.0")
                  .build();
      }
    
    
    }

然后写一个简单服务：

@ApiOperation(value = "获取某个活动")
    	@RequestMapping(value = "/{saleActivityId}", method = RequestMethod.GET)
    	public ResponseEntity<ReturnMsg<SaleActivity>> getSaleActivities(@PathVariable("saleActivityId") String saleActivityId) throws YMLibWebApplicationException{
    		Assert.notNull(saleActivityId);
    		ReturnMsg<SaleActivity> msg = new ReturnMsg<SaleActivity>();
    		List<SaleActivity> data=new ArrayList<SaleActivity>();
    		try {
    			SaleActivity  saleActivity=saleActivityRepository.findOne(saleActivityId);
    			data.add(saleActivity);
    		} catch (Exception e) {
    			throw new YMLibWebApplicationException("查询出错！");
    		}
    		msg.setData(data);
    		msg.setCode(200);
    		msg.setMsg("查询成功");
    		return ResponseEntity.ok(msg);
    	}

网上的例子：

@Api(value = "User控制器")
    @Controller
    @RequestMapping("/user")
    public class UserController {
        @ApiOperation(value = "根据用户id查询用户信息", httpMethod = "GET", produces = "application/json")
        @ApiResponse(code = 200, message = "success", response = Result.class)
        @ResponseBody
        @RequestMapping(value = "queryUserById", method = RequestMethod.GET, produces = "application/json")
        public Result queryUserById(@ApiParam(name = "userId", required = true, value = "用户Id") @RequestParam("userId") int userId, HttpServletRequest request) {
            User user = new User(userId, "haoyifen", 24);
            Result result = new Result();
            result.setCode(0);
            result.setData(user);
            result.setMessage("success");
            return result;
        }
    }

常用的几个用于生成文档的注解如下: 
    - @Api 表示该类是一个 Swagger 的 Resource, 是对 Controller 进行注解的 
    - @ApiOperation 表示对应一个 RESTful 接口, 对方法进行注解 
    - @ApiResponse 表示对不同 HTTP 状态码的意义进行描述 
    - @ApiParam 表示对传入参数进行注解

访问地址：

http://localhost:9080/ymlib/swagger-ui.html\#/

效果如下图  
![SouthEast 1][]

[SouthEast]: /images/20220602/1da2fd00929646e58d3a11bdde836cd9.png
[SouthEast 1]: /images/20220602/dde52fb92f1f4a32a098efc1073a5822.png