Swagger与Docket

spring boot 之使用Swagger配置详解_Geek-Banana的博客-CSDN博客
 (42条消息) Swagger 中 @ApiImplicitParam和@ApiImplicitParams的用途_巅峰键盘侠的博客-CSDN博客_@apiimplicitparams
SpringBoot项目中Swagger的配置和使用 - 码农小匠 - 博客园

package com.banana.demo.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 {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }

    // 配置swagger页面的头部
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Banana's SpringBoot APIs")            // 配置页面的标题
                .description("这里是Banana的swagger页面")      // 配置页面的简介
                .contact(new Contact("Banana",          // 配置页面联系，包括姓名，url，email
                        "https://blog.csdn.net/qq1515312832",
                        "dlt1997@outlook.com"))
                .version("1.0")                               // 配置页面的版本
                .build();
    }
}

1、依赖

        <!--Swagger2-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <exclusions>
                <!--swagger2.92默认依赖1.5.0版本的models和annotations
                排除掉此版本，引入一个其他版本，不让项目启动时未报Illegal DefaultValue null for parameter type integer的警告-->
                <exclusion>
                    <groupId>io.swagger</groupId>
                    <artifactId>swagger-models</artifactId>
                </exclusion>
                <exclusion>
                    <groupId>io.swagger</groupId>
                    <artifactId>swagger-annotations</artifactId>
                </exclusion>
            </exclusions>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-models</artifactId>
            <version>1.5.22</version>
        </dependency>
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-annotations</artifactId>
            <version>1.5.22</version>
        </dependency>

        <!--Swagger-UI-->
        <!--访问路径：http://localhost:8080/swagger-ui.html-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

        <!--swaggerui  几个自定义界面方便查看接口-->
        <!--访问路径：http://localhost:8080/doc.html-->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.5</version>
        </dependency>

2、注解

1.1、SwaggerConfig相关的相关注解

以下三个注解是必须的：

注解	说明
@Configuration	用于SwaggerConfig类前表明这是个配置类，项目会自动把Swagger页面加载进来
@EnableSwagger2	开启Swagger页面的使用
@Bean	用于返回Docket的方法前 Docket持有对各个接口的具体处理。

1.2、UserController相关注解

这里所说的只是与Swagger有关的注解，而非全部完整的UserController的注解：

注解	说明	例子
@Api(tags = "用户操作") @Api(description="用户注册登录")	写在Controller类之前；相当于对该Controller的一个注释在对应的Swagger页面中，会显示出这些文字	图1
以下注解写在Controller类中的接口方法前
@ApiOperation(value="用户注册", notes="注册会员") @ApiOperation(value="获取用户列表",notes="获取所有的User信息")	对当前接口方法的注释 value为简述，notes为详述这些文字会显示在Swagger界面中	图2
@ApiImplicitParam(name="username",value="用户名", dataType="String",required=true)	接口方法的参数，它会自动拼接到URL中传进来，后端可以接收到，这个参数也会自动拼接到Url之后，得到类似：http://localhost:8088/user/getUserListByName?userName=1 关于注解的参数： name：参数的名称 value：参数的含义 daatType：参数类型 required：参数是否必须	图3
@ApiImplicitParams({ 　　@ApiImplicitParam(name="name",value="用户名",dataType = "String",required=true), 　　@ApiImplicitParam(name="age",value="年龄",dataType = "Int",required=true), 　　@ApiImplicitParam(name="pwd",value="密码",dataType = "String",required=true) })	如果接口方法有多个参数，就要用@ApiImplicitParams+@ApiImplicitParam的形式组织起来

1.2.1、@Api与Controller类

1.2.2、接口方法相关的注解

1）@ApiOpertaion

2）@ApiImplicitParam

调用该接口方法时，传入的URL就是：

http://localhost:8088/user/getUserListByName?userName=1

配置好之后的界面：

3）@ApiImplicitParams

接口方法中有多个参数，需要用该注解组织起来所有的@ApiImplicitParam：

3、Docket

学习自：SpringBoot9：Swagger、任务学习（异步、定时、邮件）与分布式理论 - 喂s别闹 - 博客园

配置Swagger时，需要用到Swagger的配置类，并将其注入Spring容器中，所以需要在Config类中装配Docket实例。

在new一个Docket时，需要传入DocumentationType对象作为参数，一般情况下传入DocumentationType.SWAGGER_2就可以了：

    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2);
    }

通常情况下，我们在new Docket时，还要链式调用其他一些方法，来对Docket进一步进行设置：

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                // 只有在类上使用@Api注解标注并且在方法上使用@ApiOperation注解才会暴露给swagger，
                //这种方式没有包名的限制，可以将需要暴露的接口分散到各个包里
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .build();
    }
}

Docket.select()：设置如何扫描接口；
通过对select()的返回结果调用apis()指定扫描规则，上文中apis的参数为RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)表示只对类上用@Api注解且方法上用@ApiOpearation才会暴露给swagger
最后Build()。

配置好后，通过

http://localhost:端口/swagger-ui.html

进入Api Documentation页面查看：

posted @ 2022-06-29 21:44 ShineLe 阅读(2094) 评论(0) 编辑收藏举报

刷新页面返回顶部

ShineLee