Swagger:最流行的API框架

Swagger:最流行的API框架

Swagger简介

• 号称世界上最流行的API框架
• Restful Api 文档在线自动生成器 => API 文档 与****API 定义同步更新
• 直接运行，在线测试API
• 支持多种语言 (如:Java，PHP等)
• 官网:https://swagger.io/

Springboot集成Swagger

两个jar包：

• Springfox-swagger2
• swagger-springmvc

**要求：**jdk1.8+,否则无法运行swagger2

步骤：

1、创建一个Springboot-web项目

2、添加相应maven依赖

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2
-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-
ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

3、编写HelloController，测试确保运行成功

4、要使用swagger， 需要编写一个配置类：swaggerConfig来配置Swagger

@Configuration //标注为配置类
@EnableSwagger2 //开启Swagger2的自动配置
public class SwaggerConfig {
}

5、访问测试：http://localhost:8080/swagger-ui.html，即可看到swagger界面

配置swagger

1、swagger实例bean是Docket，所以可以通过配置Docket来配置Swagger

@Bean //配置docket以配置Swagger具体参数 
public Docket docket() {
    return new Docket(DocumentationType.SWAGGER_2);
}

2、可以通过apiInfo()属性配置文档信息

		/**
     * 配置文档信息
     *
     * @return
     */
    private ApiInfo apiInfo() {
        Contact contact = new Contact("Richard", "http://www.baidu.com", "1017176554@qq.com");
        return new ApiInfo(
                "Swagger学习", //标题
                "学习如何配置Swagger", //描述
                "v1.0", //版本号
                "http://terms.service.url/组织链接", //组织链接
                contact, //联系人信息
                "Apache 2.0", //许可
                "许可链接", //许可链接
                new ArrayList<>() //扩展信息
        );
    }

3、Docket实例关联上apiInfo()

@Bean
public Docket docket() {
  	return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
}

4、重启项目，访问测试 http://localhost:8080/swagger-ui.html 看下效果;

配置扫描的接口

1、构建Docket时通过select()方法配置怎么扫描接口

@Bean
publicDocketdocket(){
return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo())
.select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors 配置如何扫描接口
.build();
.apis(RequestHandlerSelectors.basePackage("com.richard.swagger.controller")
)
  
//其他可选项
any() // 扫描所有，项目中的所有接口都会被扫描到
none() // 不扫描接口
// 通过方法上的注解扫描，如withMethodAnnotation(GetMapping.class)只扫描get请求 withMethodAnnotation(final Class<? extends Annotation> annotation)
// 通过类上的注解扫描，如.withClassAnnotation(Controller.class)只扫描有 controller注解的类中的接口
withClassAnnotation(final Class<? extends Annotation> annotation) basePackage(final String basePackage) // 根据包路径扫描接口

2、还可以配置接口扫描过滤

@Bean
public Docket docket() {
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo())
.select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
.apis(RequestHandlerSelectors.basePackage("com.richard.swagger.controller"
))
      // 配置如何通过path过滤,即这里只扫描请求以/richard开头的接口
      .paths(PathSelectors.ant("/richard/**"))
.build();
}


//其他可选项
any() // 任何请求都扫描
none() // 任何请求都不扫描
regex(final String pathRegex) // 通过正则表达式控制 ant(final String antPattern) // 通过ant()控制

。。。

常用注解

Swagger的所有注解定义在io.swagger.annotations包下

下面列一些经常用到的，未列举出来的可以另行查阅说明:

Swagger其他皮肤

我们可以导入不同的包实现不同的皮肤定义:

1、默认的 http://localhost:8080/swagger-ui.html

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

2、bootstrap-ui http://localhost:8080/doc.html

<!-- 引入swagger-bootstrap-ui包 /doc.html--> 
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.1</version>
</dependency>

3、Layui-ui http://localhost:8080/docs.html

<!-- 引入swagger-ui-layer包 /docs.html--> 
<dependency>
    <groupId>com.github.caspar-chen</groupId>
    <artifactId>swagger-ui-layer</artifactId>
    <version>1.1.3</version>
</dependency>

4、mg-ui http://localhost:8080/document.html

<!-- 引入swagger-ui-layer包 /document.html--> 
<dependency>
    <groupId>com.zyplayer</groupId>
    <artifactId>swagger-mg-ui</artifactId>
    <version>1.0.6</version>
</dependency>