SpringBoot2配置swagger-ui可视化接口文档

swagger是一个流行的API开发框架,这个框架以“开放API声明”(OpenAPI Specification,OAS)为基础,
对整个API的开发周期都提供了相应的解决方案,是一个非常庞大的项目(包括设计、编码和测试,几乎支持所有语言)。

Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。
总体目标是使客户端和文件系统作为服务器以同样的速度来更新。
文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。

SpringBoot配置swagger

引入swagger的pom文件

     <!--swagger图形化接口-->
        <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>

        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.8.7</version>
        </dependency>

编写swagger配置文件
package org.geek.show.geek_show_manager.v1.web;

import io.swagger.annotations.Api;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
@ConditionalOnProperty(prefix = "mconfig", name = "swagger-ui-open", havingValue = "true")
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                .paths(PathSelectors.any())
                .build();
    }

    public ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("数据平台开放接口")
                .description("Rest API接口")
                .termsOfServiceUrl("https://www.geek521.com/youbitch1")
                .version("1.0")
                .build();
    }
}

首先看到我们的注解:
@Configuration代表当前是配置文件
@EnableSwagger2代表开启swagger2
@ConditionalOnProperty(prefix = “myconfig”, name = “swagger-ui-open”, havingValue = “true”)是控制当前的config是否生效,其中的参数对应着我的application.yml文件,如果我的参数为非true,那么swagger则关闭

添加到application.properties
myconfig.swagger-ui-open=true

其次springfox为我们提供了一个Docket(摘要的意思)类,我们需要把它做成一个Bean注入到spring中,显然,我们需要一个配置文件,并通过一种方式(显然它会是一个注解)告诉程序.这是一个Swagger配置文件。

springfox允许我们将信息组合成一个ApiInfo的类,作为构造参数传给Docket,(当然也可以不构造这个类,而直接使用null,但是你的这个API就显得很不专业)

那么到这里就配置完成了.启动SpringBoot服务,
访问:localhost:端口/swagger-ui.html

新建我们的controller控制器,在类上使用@Api注解,
在方法上使用@ApiOperation注解,
在参数中使用@ApiParam注解

接着我们先看效果,然后再理解注解的意思

@Api的作用是描述当前模块的作用
@ApiOperation的作用是描述当前接口的具体作用,参数还包含请求方式等
@ApiParam的作用是描述当前接口所需的参数含义,是否必选等

常用注解说明:
@Api:放在类的控制模块
@ApiOperation:放在接口方法上
@ApiImplicitParams:方法上一组参数说明
@ApiImplicitParam:一个参数的说明
@ApiResponses:一组响应说明
@ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息
@ApiModel:请求体和返回体说明
@ApiModelProperty:请求体属性说明

dev环境可以一直开启swagger,方便测试和前端对接,
线上的话就把Appliaction.properties配置中的改为false,swagger就会自动关闭,是不是很方便

发表评论

电子邮件地址不会被公开。 必填项已用*标注