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 {
@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的旅程吧~
