springboot + swagger3 简单整合

1、首先还是新建springboot工程，导入相关依赖。

        <!--swagger3 文档-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>
        <!--swagger美化-->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.6</version>
        </dependency>

我是导入的swagger3，第一个springfox集成了swagger，第二个美化可有可无。

2、解决冲突

从springboot 2.6.x开始，就与swagger产生了冲突，这时我用了application.yml配置，暂时可用

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

3、需要配置config

package com.hc.store.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.oas.annotations.EnableOpenApi;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@EnableOpenApi
@Configuration
public class SwaggerConfig {

    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .groupName("hc_conf")
                .select()
                //需要放出的接口
                .apis(RequestHandlerSelectors.basePackage("com.hc.store.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("接口文档")
                .description("swagger3")
                .contact(new Contact("chajintao", "", "220780****@qq.com"))
                .version("1.0")
                .build();
    }


}

这里有注解必须要加@EnableOpenApi，代表引入了swagger3。

配置类是配置需要显示的控制类，即Docket，还有一些文档信息。

title是标题，description是对该文档的描述，contact是写自己的联系方式，version是定义版本，groupName是项目名称，apis(RequestHandlerSelectors.basePackage("控制层路径"))是你自己的的控制层。

4、然后就是controller层了

package com.hc.store.controller;


import com.hc.store.model.Product;
import com.hc.store.model.User;
import com.hc.store.service.ProductService;
import com.hc.store.service.UserService;
import com.hc.store.util.JsonResult;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

import java.util.HashMap;
import java.util.List;
import java.util.Map;

@Api(tags = "swagger控制器")
@RestController
@RequestMapping("/swaggers")
public class SwaggerController extends BaseController {

    @Autowired
    private UserService userService;
    @Autowired
    private ProductService productService;


    @ApiOperation(value = "通过主键id查询用户")
    @ApiImplicitParam(name = "id", value = "用户id", required = true, dataType = "User")
    @RequestMapping("/getUserByUid")
    public JsonResult<User> getUserByUid(Integer id) {
        User user = userService.getUserByUid(id);
        return new JsonResult<>(OK,user);
    }

    @ApiOperation(value = "商品数据分页", notes = "")
    @RequestMapping("/getAllPros")
    public Map<String,Object> getAllPros(@RequestParam(required = false,defaultValue = "1") Integer page, @RequestParam(required = false,defaultValue = "10") Integer limit) {

        Integer count = productService.getCount();

        List<Product> list = productService.getPros(page,limit);


        Map<String,Object> map=new HashMap<String,Object>();
        map.put("code",0);
        map.put("msg","");
        map.put("count",count);
        map.put("data",list);
        System.out.println(map.toString());
        return map;
    }
}

这时候就已经完成了，就是特别简单的整合，不深入。

@Api用在controller类，描述API接口，tags是分类，controller下所有接口生成的文档都在tags下

@ApiOperation用在方法上，描述接口方法，value是方法描述，notes是提示内容，tags重新分组

@ApiParam用在入参上面，描述参数，name是参数名，value是说明，required是否必填

剩下的我都没有设置，在这里也简单记一下，万一忘了可以查看。

@ApiModel() 用在类上，value表示对象名称，description表示描述

@ApiModelProperty() 用在方法、字段上，value是字段说明，name是重写属性名，dataType是重写属性类型，required是否必填，example是举例说明，hidden是隐藏

大概就那么多了，比较简单，能用是第一，用好才是大神的行为。