SpringBoot项目集成Swagger2

微风粼粼

已于 2024-08-09 18:00:36 修改

阅读量1.3k

点赞数 1

于 2022-10-27 15:23:49 首次发布

本文链接：https://blog.csdn.net/ITKidKid/article/details/127553452

版权

前言

使用swagger2编写接口文档方便快捷，swagger2是为了方便前后端分离项目的交互，后端可以用来编写字段的描述，方便前端在对接口的了解每个字段的含义，不会把字段搞混，减轻前后端交互的压力，提高开发效率。

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

注解说明

注解名	位置	描述
`@Api`	类上	标记该类为一个Swagger资源(API)，通常用在Controller上。可设置标签、描述等。
`@ApiOperation`	方法上	对一个API方法的描述，包括HTTP方法、请求路径、摘要、操作ID等。
`@ApiParam`	方法参数上	对API方法的参数进行描述，包括名称、是否必需、参数类型、默认值等。
`@ApiModel`	类上	用于对象作为请求体或响应体时，描述该对象的结构。
`@ApiModelProperty`	类的属性上	描述一个模型属性的意义，包括是否必需、默认值、示例值等。
`@ApiResponse`	方法上或@ApiResponses上	描述一个API响应的信息，如响应码、描述、响应体类型等。
`@ApiResponses`	方法上	包含多个@ApiResponse注解，用于表示一个API可能返回的所有响应。
`@ApiIgnore`	类、方法或参数上	忽略该元素，使其不生成到Swagger文档中。
`@ApiImplicitParam`	方法上	用于描述非请求体中的参数，如路径参数、查询参数、头信息等。
`@ApiImplicitParams`	方法上	包含多个@ApiImplicitParam注解，用于表示一个方法可能包含的所有隐式参数。
`@Authorization`	类或方法上	已废弃，建议使用全局安全配置或@SecurityRequirement。
`@SecurityDefinitions`	配置类上	定义安全方案，如OAuth2、API密钥等，现已被`@SecurityScheme`替代。
`@SecurityScheme`	配置类上	定义安全方案，如OAuth2、Basic Auth等，用于全局安全配置。
`@SecurityRequirement`	类或方法上	引用在@SecurityDefinitions或@SecurityScheme中定义的安全方案，表示API需要的安全认证。
`@Deprecated`	用于修饰方法或类，表示它们已经过时。	无属性，通常用于提醒开发者API已经不再推荐使用
`@SecurityDefinition`	定义API的认证方式。	`name`: 认证方式名称 `type`: 认证类型（如`apiKey`、`basicAuth`、`oauth2`） `description`: 描述信息 `in`: 认证信息的发送位置（如`header`、`query`）
`@ApiParamImplicit`	用于修饰方法的参数，	表示方法的隐式参数。可以设置 name、value 等属性来描述参数。
`@ApiParamImplicitHeader`	用于修饰方法的参数，	表示方法的隐式头参数。可以设置 name、value 等属性来描述头参数。
`@ApiParamImplicitQuery`	用于修饰方法的参数，	表示方法的隐式查询参数。可以设置 name、value 等属性来描述查询参数。
`@ApiParamImplicitCookie`	用于修饰方法的参数，	表示方法的隐式 cookie 参数。可以设置 name、value 等属性来描述 cookie 参数。
`@ApiModelImplicit`	用于修饰方法的参数，	表示方法的隐式模型。可以设置 name、value 等属性来描述模型。
`@ApiModelImplicitProperty`	用于修饰方法的参数，	表示方法的隐式属性。可以设置 name、value 等属性来描述属性。

常用注解

swagger通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等。
以下是一些在Swagger（特别是Swagger 2.x，通过Springfox实现）中常用的注解。

注解名称	属性名称	备注	简要说明
`@Api`	value	url的路径值	用来定义整个Controller的基路径，但不直接映射到具体的URL上，而是作为Swagger UI中该Controller下所有API的根路径。
	tags	如果设置这个值，value的值会被覆盖	用于为Controller分类，Swagger UI会根据这个值来分组显示API。
	description	对api资源的描述	提供对整个Controller或API接口的详细描述。
	basePath	基本路径	在Swagger 2.x中，这个属性通常不是通过`@Api`注解来设置的，而是全局配置或通过其他方式指定。
	position	如果配置多个Api，想改变显示的顺序位置	用来控制Swagger UI中API列表的显示顺序，但注意，并非所有版本的Swagger UI都支持此功能。
`@ApiOperation`	value	操作的简要说明	用来描述一个API接口的作用。
	notes	对操作的详细说明	提供对API接口的详细描述，比`value`更详细。
	tags	可以重新覆盖类级别的tags	在方法级别重新指定或覆盖Controller级别的`tags`。
	response	默认响应类	指定API接口的默认响应类型。
	responseContainer	响应的包装类型	指定响应数据的包装类型，如List或Set。
	produces	如, “application/json, application/xml”	指定API接口支持的响应媒体类型。
	consumes	如, “application/json, application/xml”	指定API接口支持的请求媒体类型。
	protocols	协议类型，如: http, https, ws, wss	指定API接口支持的协议类型，但通常不常用。
	authorizations	高级特性认证时配置	指定API接口所需的安全认证方式。
	hidden	配置为true，将在文档中隐藏	将API接口从Swagger UI中隐藏。
`@ApiParam`	name	参数名	指定请求参数的名称。
	value	参数的简要说明	对请求参数的简要描述。
	required	是否必须传值	指定请求参数是否必须。
	defaultValue	参数的默认值	为请求参数提供默认值。
`@ApiModel`	value	对象的名称	用来描述一个Java类的名称，该类将被用作API接口的请求或响应体。
	description	对api模型的描述	对API模型（即Java类）的详细描述。
`@ApiModelProperty`	value	字段说明	对模型属性的简要描述。
	example	示例值	为模型属性提供一个示例值。
	hidden	是否隐藏	将模型属性从Swagger UI中隐藏。
	required	是否必须	指定模型属性是否必须。
`@ApiImplicitParams`	-	-	用于包含多个`@ApiImplicitParam`注解，以定义多个请求参数。
`@ApiImplicitParam`	`name`	参数名	指定请求参数的名称。
	`value`	参数的简要说明	对请求参数的简短描述。
	`dataType`	参数的数据类型	指定请求参数的数据类型（如`"integer"`, `"string"`等）。
	`paramType`	参数类型	指定请求参数的来源（如`"query"`, `"path"`, `"header"`, `"body"`, `"form"`）。
	`required`	是否必须	指定请求参数是否必须提供。
	`defaultValue`	参数的默认值	为请求参数提供一个默认值。
	`example`	示例值	为请求参数提供一个具体的示例值。

@ApiModel：用对象来接收参数，放在类上面
@ApiModelProperty：用对象接收参数时，描述对象的一个字段，放在字段上面

@Data
@ApiModel(value="User对象", description="用户类")
public class User {

    @ApiModelProperty(value = "用户ID")
    private Integer id;

    @ApiModelProperty(value = "名称")
    private String name;

    @ApiModelProperty(value = "年龄")
    private Integer age;
    
}

最终界面展示
在这里插入图片描述

@Api：修饰整个类，放在类上面，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口，放在方法或接口上
@ApiParam：单个参数描述

-- 用法
@Api(tags = "用户控制器")
@Controller
public class BasicController {
    @RequestMapping(value = "/user",method = RequestMethod.GET)
    @ApiOperation(value = "获取用户信息(名称)", notes = "根据用户名称获取用户信息")
    @ResponseBody
    public User getUser(@RequestParam @ApiParam(name = "name",value = "名称",required = true) String name) {
        User user = new User();
        user.setName(name);
        user.setAge(666);
        return user;
    }
}

最终界面展示
在这里插入图片描述

@ApiImplicitParam：一个请求参数
@ApiImplicitParams：多个请求参数、

这两个需要配合使用

@Api(tags = "用户控制器")
@Controller
public class BasicController {

    @ApiOperation(value = "获取用户信息(ID)", notes = "根据用户ID获取用户信息")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "用户的唯一标识符", required = true, dataType = "int", paramType = "query"),
            @ApiImplicitParam(name = "name", value = "用户的名称", required = false, dataType = "string", paramType = "query")
    })
    @GetMapping("/getUserInfo")
    @ResponseBody
    public String getUserInfo(@RequestParam int id, @RequestParam(required = false) String name) {
        // 处理获取用户信息的逻辑
        return "用户ID: " + id + (name != null ? ", 用户名: " + name : "");
    }
}

最终界面展示
在这里插入图片描述

1、添加相关依赖

       <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
            <exclusions>
                <exclusion>
                    <groupId>io.swagger</groupId>
                    <artifactId>swagger-annotations</artifactId>
                </exclusion>
                <exclusion>
                    <groupId>io.swagger</groupId>
                    <artifactId>swagger-models</artifactId>
                </exclusion>
            </exclusions>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>
        <!--swaggerui  几个自定义界面方便查看接口、比原始的swagger-ui.html界面美观-->
        <!--需要在swaggerui配置类上面添加@EnableSwaggerBootstrapUI注解，不然不生效-->
        <!--访问路径：http://IP:端口号/doc.html-->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.6</version>
        </dependency>
        <dependency>
            <groupId>com.google.guava</groupId>
            <artifactId>guava</artifactId>
            <version>25.1-jre</version>
        </dependency>
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-annotations</artifactId>
            <version>1.6.0</version>
        </dependency>
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-models</artifactId>
            <version>1.6.0</version>
        </dependency>

2、创建相关工具类

/**
 * @Author zzw
 * @Create
 * @Description
*/
@Configuration
@EnableSwagger2
@EnableSwaggerBootstrapUI
public class Swagger2Config {

    @Bean
    public Docket createRestApi(Environment environment) {
        //设置swagger环境
        Profiles profiles = Profiles.of("dev", "test");
        //通过environment.acceptsProfiles 判断是否自己设定在自己设定的环境中
        boolean flag = environment.acceptsProfiles(profiles);
        return new Docket(DocumentationType.SWAGGER_2)
                //配置是否启用Swagger，如果是false，在浏览器将无法访问
                .enable(flag)
                // 分组名称
                .groupName("test")
                //用于定义API主界面的信息
                .apiInfo(apiInfo())
                //用于控制接口被swagger做成文档
                .select()
                //扫描路径选择
                .paths(
                        PathSelectors.any() // 满足条件的路径，该断言总为true
                        //.none() // 不满足条件的路径，该断言总为false（可用于生成环境屏蔽 swagger）
                        //.ant("/user/**") // 满足字符串表达式路径
                        //.regex("") // 符合正则的路径
                )
                // 下面的包名为项目controller所在包
                .apis(RequestHandlerSelectors.
                        basePackage("com.example.demo.demos.web")) // 扫描指定包下的接口，最为常用
                        //.any() // 扫描全部的接口，默认
                        //.none() // 全部不扫描
                        //.withClassAnnotation(RestController.class) // 扫描带有指定注解的类下所有接口
                        //.withMethodAnnotation(PostMapping.class) // 扫描带有只当注解的方法接口
                .build()
                // 配置安全策略
                .securityContexts(securityContexts())
                // 通过Swagger2的securitySchemes配置全局参数
                .securitySchemes(securitySchemes());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //文档标题
                .title("自定义标题")
                //接口概述
                .description("自定义描述")
                //联系人的信息
                .contact(new Contact("联系人名称","http:IP:端口号/doc.html", "123@qq.com"))
                //版本号
                .version("1.0")
                //定义服务的域名
                //.termsOfServiceUrl(String.format("url"))
                //.license("LICENSE")//证书
                //.licenseUrl("http://www.guangxu.com")//证书的url
                .build();
    }

    private List<ApiKey> securitySchemes() {
        // 设置请求头信息
        List<ApiKey> result = new ArrayList<>();
        // 参数一name为参数名，参数二keyname为参数key，参数三passAs为参数存放位置，其值有header、query、path等，其中
        // header为请求头，query为请求参数，path为请求路径
        ApiKey apiKey = new ApiKey("Authorization", "Authorization", "Header");
        result.add(apiKey);
        return result;
    }

    // 在Swagger2的securityContexts中通过正则表达式，设置需要或不需要使用参数的接口
    private List<SecurityContext> securityContexts() {
        List<SecurityContext> result = new ArrayList<>();
        // 调用下面定义的getContextByPath()，设置需要登录认证的路径，比如此处的/hello/.*
        result.add(getContextByPath("/hello/.*"));
        // 上面配置后，在Swagger文档中访问/hello路径时，需要用到securitySchemes()方法中配置的全局参数
        return result;
    }
    private SecurityContext getContextByPath(String pathRegex) {
        return SecurityContext.builder()
                .securityReferences(defaultAuth())
                .forPaths(PathSelectors.regex(pathRegex))
                .build();
    }
    private List<SecurityReference> defaultAuth() {
        List<SecurityReference> result = new ArrayList<>();
        // AuthorizationScope权限范围对象，其参数一scope为权限范围名称，global表示全局，其参数二为范围描述
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        result.add(new SecurityReference("Authorization",authorizationScopes));
        return result;
    }

}

3、添加配置

解决swagger2启动错误：Cannot invoke “org.springframework.web.servlet.mvc.condition.PatternsRequestCondition.toString()” because the return value of “springfox.documentation.spi.service.contexts.Orderings.patternsCondition(springfox.documentation.RequestHandler)” is null

添加配置( # 解决swagger2的错误问题)

application.properties文件配置

spring.mvc.pathmatch.matching-strategy = ant-path-matcher

application.yml文件配置

spring:
  mvc:
    pathmatch:
      matching-strategy: ant-path-matcher

4、启动项目

使用 http:IP:端口号/doc.html 或者 http:IP:端口号/swagger-ui.html 进行访问

在这里插入图片描述

$[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-pyAYoPDZ-1666855270203)(C:\Users\Administrator\AppData\Roaming\Typora\typora-user-images\image-20221027145730114.png)]$ 至此swagger2就集成完毕了。