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文件

        <!--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;/*** Created by 張燿峰** @author 孤* @date 2019/5/24* @Varsion 1.0*/
@Configuration
@EnableSwagger2
@ConditionalOnProperty(prefix = "mconfig", name = "swagger-ui-open", havingValue = "true")
public class SwaggerConfig {@Beanpublic 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的旅程吧~