Swagger的应用及配置

RestFul Api文档—Swagger的应用及配置

Swagger的应用背景

现如今前后端开分离已经成为了最流行的一种开发模式，在这样的开发模式中如果前端人员和后端人员无法做到即使协商，尽早解决问题，最终就会导致问题集中爆发。

这个问题的解决方案之一，就是使用Swagger

Swagger简介

RestFul Api文档在线自动生成工具=》Api文档与API定义同步更新
直接运行，可以在线测试API接口
支持多种语言

官网：https://swagger.io/

Swagger的使用步骤：

1.添加依赖

集成使用Swagger需要导入两个依赖：

         <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.1</version>
        </dependency>

这里的ui依赖是前端文档显示页面所依赖的jar包，集成Swagger之后的，文档的地址默认为：localhost:端口号/swagger-ui.html

个人建议：
如果你成功集成了Swagger并且通过入口地址进入了文档显示页面，这时你会发现原始的页面不太好看(个人观点)，所有这里给大家推荐一下我自己使用之后觉得还不错的一个由别的大佬重新制作之后的新界面依赖包：

使用起来也特别简单，只需要使用下面的依赖替换掉上面的springfox-swagger-ui即可：

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

这里需要注意一点：

当我们使用了这个新的依赖替换原始以来之后，接口文档的默认地址变成了：localhost:端口号/doc.html

配置config

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 //开启swagger
public class Swagger2Configuration {

    //api接口包扫描路径
    public static final String SWAGGER_SCAN_BASE_PACKAGE = "com.baixiaoyuan.management.controller";

    public static final String VERSION = "1.0.0";

	 //配置Swagger2的bean实例
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
				.enable(false)  //配置是否启用swagger  false关闭
                .select()
				//RequestHandlerSelectors配置扫描方式
             .apis(RequestHandlerSelectors.basePackage(SWAGGER_SCAN_BASE_PACKAGE))
                .paths(PathSelectors.any()) // 可以根据url路径设置哪些请求加入文档，忽略哪些请求
                .build();
    }

    //配置swagger信息=apiInfo
    private ApiInfo apiInfo() {
	//作者信息
	//Contact contact = new Contact(name:"baixiaoyuan",url:"https://baixiaoyuan.com",email:"[email protected]")
        return new ApiInfoBuilder()
                .title("系统接口文档") //设置文档的标题
                .description("系统的接口介绍") // 设置文档的描述
                .version(VERSION) // 设置文档的版本信息-> 1.0.0 Version information
                .termsOfServiceUrl("http://localhost:8080/doc.html") // 设置文档的License信息->1.3 License information
                .build();
    }
}

以上只是一些比较基础的配置与应用，Swagger还是比较好用且容易上手的，如果有兴趣，大家可以自己再去深入的了解一下。

由于自己也处于学习阶段，写文章的目的第一个是把自己得到的东西做一个分享，其次也是为了巩固一下自己的所学所得，也是为自己的知识做一个备份。第一次写文章，有什么不足之处请大家留下宝贵的意见。