springboot集成swagger2

目录

1.swagger是什么?

2.SpringBoot配置swagger

3.如何使用swagger生成接口文档:


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

1.swagger是什么?

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

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

2.SpringBoot配置swagger

1>引入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>

2>编写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;

/**
 * Created by 張燿峰
 *
 * @author 孤
 * @date 2019/5/24
 * @Varsion 1.0
 */
@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("SeClover数据平台开放接口")
                .description("Rest API接口")
                .termsOfServiceUrl("https://blog.csdn.net/youbitch1")
                .version("1.0")
                .build();
    }
}
 

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

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

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

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

3.如何使用swagger生成接口文档:

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

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

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

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

dev环境可以一直开启swagger,方便测试和前端对接,
线上的话就把Appliaction.yml配置中的
 

改为false,swagger就会自动关闭,是不是很方便

开启swagger的旅程吧~

  • 0
    点赞
  • 0
    收藏
    觉得还不错? 一键收藏
  • 0
    评论

“相关推荐”对你有帮助么?

  • 非常没帮助
  • 没帮助
  • 一般
  • 有帮助
  • 非常有帮助
提交
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值