springboot 整合swagger

springboot版本过高导致报错解决参考

https://blog.csdn.net/nxg0916/article/details/123382012

整合可以参考

SpringBoot集成swagger-ui以及swagger分组显示_程序员青戈的博客-CSDN博客_springboot swagger 分组

依赖

<dependency>
    <groupId>io.springfoxgroupId>
    <artifactId>springfox-swagger2artifactId>
    <version>2.7.0version>
dependency>
<dependency>
    <groupId>io.springfoxgroupId>
    <artifactId>springfox-swagger-uiartifactId>
    <version>2.7.0version>
dependency>

配置类

package com.angen.springboot_test2.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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
 
 
 
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    /**
     * 创建API应用
     * apiInfo() 增加API相关信息
     * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，
     * 本例采用指定扫描的包路径来定义指定要建立API的目录。
     *
     * @return
     */
    @Bean
    public Docket restApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("标准接口")
                .apiInfo(apiInfo("Spring Boot中使用Swagger2构建RESTful APIs", "1.0"))
                .useDefaultResponseMessages(true)
                .forCodeGeneration(false)
                .select()
                //配置包扫描
                .apis(RequestHandlerSelectors.basePackage("com.angen.springboot_test2.controller"))
                .paths(PathSelectors.any())
                .build();
    }
 
    /**
     * 创建该API的基本信息（这些基本信息会展现在文档页面中）
     * 访问地址：http://ip:port/swagger-ui.html
     *
     * @return
     */
    private ApiInfo apiInfo(String title, String version) {
        return new ApiInfoBuilder()
                .title(title)
                .description("更多请关注: https://baidu.com")
                .termsOfServiceUrl("https://baidu.com")
                .contact(new Contact("xx", "https://baidu.com", "123456@163.com"))
                .version(version)
                .build();
    }
 
}

然后我们启动项目，打开http://ip:port/swagger-ui.html即可访问到接口文档

---

RESTful风格接口

/**
     * 通过id获取栏目
     */
    @GetMapping("getById/{id}")
    @ApiOperation(value = "根据id获取参数", notes = "根据id获取参数")
    @ApiImplicitParam(name = "id", value = "编号(必填)", required = true, dataType = "Integer", paramType = "path")
    public GameBigcate findById(@PathVariable("id") Integer id) {
        return cateService.findById(id);
    }

常用注解

@Api

作用：作用在类上

属性：

1，tags:给类起一个别名，可以起多个

@Api(tags = "栏目接口")

@ApiOperation

作用：可以做用在类上，或者作用在方法上。

属性：

1，value，给当前方法或者类一些描述 ，简单描述

2，notes，一样的是可以给一些描述，详细描述

@ApiOperation(value = "get请求，不用传递参数", notes = "栏目接口-通过get请求获取所有的顶级栏目")

@ApiParam

作用：主要作用在描述方法的参数

属性：

1,name:与传过来参数一致

2,value:详细描述信息

3,required：是否是必须的参数

案例

    /**
     * 通过id获取栏目
     */
    @GetMapping("getById")
    @ApiOperation(value = "根据id获取参数", notes = "根据id获取参数")
    //@ApiImplicitParam(name = "id", value = "编号(必填)", required = true, dataType = "Integer", paramType = "path")
    public GameBigcate findById(
            @ApiParam(name="id",value ="顶级栏目id",required = true )
            @RequestParam Integer id) {
        return cateService.findById(id);
    }

@ApiIgnore

作用：忽略当前类或者方法或者参数不生成文档

@ApiImplicitParam

作用在方法上，在方法上描述方法的参数

name：对应参数名

value：描述

required：是否必填传递

dataType：数据类型

paramType ：查询参数类型，这里有几种形式：
        path 以地址的形式提交数据
        query 直接跟参数完成自动映射赋值
        body 以流的形式提交 仅支持POST
        header 参数在request headers 里边提交
        form 以form表单的形式提交 仅支持POST

@ApiImplicitParams

@ApiModel

一般作用域实体类上，用于返回值类型

属性：

value:描述

@ApiModelProperty

作用在实体类属性上

属性：

value参数类型为String，作用为此属性的简要描述。

name参数类型为String，作用为允许重写属性的名称。 字段名称

allowableValues参数类型为String，作用为限制此参数存储的长度。

access()参数类型为String，作用为允许从API文档中过滤属性

notes参数类型为String，作用为该字段的注释说明

dataType参数类型为String，作用为参数的数据类型。

required参数类型为String，作用为指定参数是否可以为空，默认为false

position参数类型为int，作用为允许显式地对模型中的属性排序。

hidden参数类型为boolean，作用为是否允许模型属性隐藏在Swagger模型定义中，默认为false。

example参数为String类型，作用为属性的示例值。

readOnly参数类型为boolean，作用为是否允许将属性指定为只读，默认为false。

reference参数类型为String，作用为指定对对应类型定义的引用，重写指定的任何其他数据名称。

allowEmptyValue参数类型为boolean，作用为是否允许传递空值，默认为false