SpringBoot整合Swagger2 详解

简介: SpringBoot整合Swagger2 详解

Swagger 是一组围绕 OpenAPI 规范构建的开源工具,可以帮助您设计、构建、记录和使用 REST API。主要的 Swagger 工具包括:

  • Swagger Editor – 基于浏览器的编辑器,您可以在其中编写 OpenAPI 定义。
  • Swagger UI – 将 OpenAPI 定义呈现为交互式文档。
  • Swagger Codegen – 从 OpenAPI 定义生成服务器存根和客户端库。
  • Swagger Editor Next (beta) – 基于浏览器的编辑器,您可以在其中编写和查看OpenAPI和AsyncAPI定义。
  • Swagger Core – 与 Java 相关的库,用于创建、消费和使用 OpenAPI 定义。
  • Swagger Parser – 用于解析 OpenAPI 定义的独立库
  • Swagger APIDom – 提供单一的统一结构,用于跨各种描述语言和序列化格式描述 API

一、常用注解

1.@Api

@Api 注解用于标注一个Controller(Class)。在默认情况下,Swagger-Core只会扫描解析具有@Api注解的类,而会自动忽略其他类别资源(JAX-RS endpoints,Servlets等等)的注解。

属性

描述

value

url的路径值

tags

如果设置这个值、value的值会被覆盖

description

对api资源的描述

basePath

基本路径可以不配置

position

如果配置多个Api 想改变显示的顺序位置

produces

For example, "application/json, application/xml"

produces

For example, "application/json, application/xml"

consumes

For example, "application/json, application/xml"

protocols

Possible values: http, https, ws, wss.

authorizations

高级特性认证时配置

hidden

配置为true 将在文档中隐藏

2.@ApiOperation

@ApiOperation 注解在用于对一个操作或HTTP方法进行描述。具有相同路径的不同操作会被归组为同一个操作对象。不同的HTTP请求方法及路径组合构成一个唯一操作。

主要属性:

属性

描述

value

url的路径值

tags

如果设置这个值、value的值会被覆盖

description

对api资源的描述

basePath

基本路径可以不配置

position

如果配置多个Api 想改变显示的顺序位置

produces

For example, "application/json, application/xml"

consumes

For example, "application/json, application/xml"

protocols

Possible values: http, https, ws, wss.

authorizations

高级特性认证时配置

hidden

配置为true 将在文档中隐藏

response

返回的对象

responseContainer

这些对象是有效的 "List", "Set" or "Map".,其他无效

httpMethod

"GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH"

code

http的状态码 默认 200

extensions

扩展属性

3.@ApiParam

@ApiParam作用于请求方法上,定义api参数的注解。

主要属性:

属性

描述

name

属性名称

value

属性值

defaultValue

默认属性值

allowableValues

可以不配置

required

是否属性必填

access

不过多描述

allowMultiple

默认为false

hidden

隐藏该属性

example

举例子

4.@ApiImplicitParams、@ApiImplicitParam

@ApiImplicitParams、@ApiImplicitParam 都可以定义参数.

(1).@ApiImplicitParams:用在请求的方法上,包含一组参数说明

(2).@ApiImplicitParam:对单个参数的说明

主要属性:

5.@ApiResponses、@ApiResponse

@ApiResponses、@ApiResponse进行方法返回对象的说明。

6.@ApiModel、@ApiModelProperty

@ApiModel用于描述一个Model的信息(这种一般用在post创建的时候,使用@RequestBody这样的场景,请求参数无法使用@ApiImplicitParam注解进行描述的时候)。

@ApiModelProperty用来描述一个Model的属性

使用场景

@ApiModel 用在模型类上,对模型类作注解

@ApiModelProperty 用在属性上,对属性作注解

7.@PathVariable

@PathVariable用于获取get请求url路径上的参数,即参数绑定的作用,通俗的说是url中"?"前面绑定的参数。

二、SpringBoot整合Swagger

1、引入依赖

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

2、 创建Swagger 的配置类

@EnableSwagger2
@Configuration
@ConditionalOnProperty(name = "swagger.enable", havingValue = "true")//配置Swagger 的开关
public class Swaggerconfig {
    public static final String SWAGGER_SCAN_BASE_PACKAGE = "com";
    public static final String VERSION = "1.0.0";
//    @Value("${swagger.enable}")
//    private boolean swaggerShow;
    @Bean
    public Docket createRestApi() {
//        boolean a = swaggerShow;
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("wechat")
                .apiInfo(apiInfo())
                .select()
                .apis(Predicates.or(RequestHandlerSelectors.basePackage(SWAGGER_SCAN_BASE_PACKAGE)))
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any()) // 可以根据url路径设置哪些请求加入文档,忽略哪些请求
                .build()
                .securitySchemes(securityScheme())
                .securityContexts(securityContexts());
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("单词计数服务") //设置文档的标题
                .description("单词计数服务 API 接口文档") // 设置文档的描述
                .version(VERSION) // 设置文档的版本信息-> 1.0.0 Version information
                .termsOfServiceUrl("http://www.baidu.com") // 设置文档的License信息->1.3 License information
                .build();
    }
    private List<SecurityContext> securityContexts() {
        List<SecurityContext> securityContexts = new ArrayList<>();
        securityContexts.add(
                SecurityContext.builder()
                        .securityReferences(defaultAuth())
                        .forPaths(PathSelectors.regex("^(?!auth).*$"))
                        .build());
        return securityContexts;
    }
    //增加全局认证
    List<SecurityReference> defaultAuth() {
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        List<SecurityReference> securityReferences = new ArrayList<>();
        securityReferences.add(new SecurityReference("token", authorizationScopes));//验证增加(有许多教程说明中这个地方是Authorization,导致不能带入全局token,因为securitySchemes()方法中header写入token,所以这个地方我改为token就可以了)
        return securityReferences;
    }
    private ParameterBuilder parameterBuilder(String name, String desc, String type, String parameterType, boolean required) {
        ParameterBuilder tokenPar = new ParameterBuilder();
        tokenPar.name(name).description(desc).modelRef(new ModelRef(type)).parameterType(parameterType).required(required).build();
        return tokenPar;
    }
    @Bean
    List<ApiKey> securityScheme() {
        List<ApiKey> apiKeyList = new ArrayList();
        apiKeyList.add(new ApiKey("token", "token", "header"));
        return apiKeyList;
    }

Swagger官网 http://swagger.io/

文章下方有交流学习区!一起学习进步!也可以前往官网,加入官方微信交流群 你的支持和鼓励是我创作的动力❗❗❗

Doker的成长,欢迎大家一起陪伴!!!

我发好文,兄弟们有空请把我的官方旗舰店流量撑起来!!!

官网:Doker 多克; 官方旗舰店Doker 多克 官方旗舰店-淘宝网 全品优惠

目录
相关文章
|
8天前
|
Java API Spring
【一】springboot整合swagger
【一】springboot整合swagger
35 0
|
8天前
|
Java API Spring
Swagger使用-Spring Boot整合Swagger
Swagger使用-Spring Boot整合Swagger
50 0
|
8天前
|
XML Java 测试技术
【二】springboot整合自定义swagger
【二】springboot整合自定义swagger
27 0
|
8天前
|
Java Spring
Spring Boot3整合knife4j(swagger3)
Spring Boot3整合knife4j(swagger3)
380 1
|
8天前
|
Java API
SpringBoot 整合swagger3.X
SpringBoot 整合swagger3.X
|
8天前
|
Java API
SpringBoot中的Swagger2如何使用?
SpringBoot中的Swagger2如何使用?
27 1
|
8天前
|
Java 应用服务中间件 网络安全
Nginx配置静态页面+springboot应用+swagger+SSL的实现
Nginx配置静态页面+springboot应用+swagger+SSL的实现
|
8天前
|
Java Maven
【SpringBoot专题_02】springboot集成Swagger详细教程
【SpringBoot专题_02】springboot集成Swagger详细教程
31 0
|
8天前
|
Java API
SpringBoot集成Swagger2组件
SpringBoot集成Swagger2组件
31 1