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

SpringBoot配置swagger-ui

[提前声明]
文章由作者:张耀峰 结合自己生产中的使用经验整理,最终形成简单易懂的文章
写作不易,转载请注明,谢谢!
代码案例地址: ?https://github.com/Mydreamandreality/sparkResearch

---

每天写文档写到吐?
头花又稀疏了几分?
前后端分离开发还需要提前定制接口?
陪女朋友看电影的计划又泡汤了?
累吗兄弟 ?让swagger自动化API简化我们的工作吧!

swagger是什么?

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

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

SpringBoot配置swagger

引入swagger的pom文件

        
        
            io.springfox
            springfox-swagger2
            2.9.2
        

        
            io.springfox
            springfox-swagger-ui
            2.9.2
        

        
            com.github.xiaoymin
            swagger-bootstrap-ui
            1.8.7
        

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

---

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

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

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

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

---

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

---

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

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

开启swagger的旅程吧~