Swagger-SpringBoot-REST API的简单使用

关于Swagger

Swagger是一款可以自动生成API的框架

在SpringBoot项目中使用Swagger

• 首先，我们要使用，就必须导入相关依赖

<dependency>
      <groupId>io.springfoxgroupId>
      <artifactId>springfox-swagger2artifactId>
      <version>2.9.2version>
dependency>

• 然后编写SpringFox（也就是Swagger）的配置文件

@Configuration//标明是配置文件，需要自动装配
@EnableSwagger2//使用Swagger2
public class SpringFoxConfig {
    @Bean//实例化Docket对象
      public Docket apiDocket() {
        return new Docket(DocumentationType.SWAGGER_2);
    }
}

• 运行启动类，然后再浏览器中输入：
  http://localhost:8080/v2/api-docs

这里面是描述API的swagger元数据，也就是SpringFox将项目信息封装成JSON对象，然后交给Swagger，让Swagger处理成API文档。我们可以将这些数据复制，然后粘贴到swagger编辑器，swagger编辑器会自动识别转换，如下图，右栏就是生成的API文档。

那么，如何在SpringBoot项目中自动生成呢？

使用Swagger生成REST API

• 要使用Swagger生成REST API就需要导入Swagger-UI依赖：

<dependency>
    <groupId>io.springfoxgroupId>
    <artifactId>springfox-swagger-uiartifactId>
    <version>2.9.2version>
dependency>

• 然后编写一个Controller类，让生成的API更加直观

package com.lei.swagger.controller;

import io.swagger.annotations.Api;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class HelloController {
    @GetMapping("/hello1")
    public String hello1(){
        return "hello1";
    }
    @PostMapping("/hello2")
    public String hello2(){
        return "hello2";
    }
}

• 编辑配置文件
  将之前的配置文件改为：

@Configuration//标明是配置文件，需要自动装配
@EnableSwagger2//使用Swagger2
public class SpringFoxConfig {
    @Bean//实例化Docket对象
      public Docket apiDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }

    //为了使生成的ui不那么简陋，我们可以自己配置一些信息，swagger会显示在生成的页面上
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot中使用Swagger2构建RESTful API")//页面标题
                .description("rest api 文档构建利器")//描述
                .termsOfServiceUrl("localhost:8080")
                .contact(new Contact("leigoo","localhost:8080","[email protected]"))//链接
                .version("1.0")//版本号
                .build();
    }
}

• 输入生成的UI地址：http://localhost:8080/swagger-ui.html
• 
  
• @ EnableSwagger2支持Swagger 2的SpringFox支持。
• DocumentationType.SWAGGER_2告訴Docket bean我們正在使用Swagger規範的版本2。
• select（）創建一個構建器，用於定義哪些控制器及其生成的文檔中應包含哪些方法。
• apis（）定義要包含的類（控制器和模型類）。這裡我們包括所有這些，但您可以通過基本包，類註釋等來限制它們。
• paths（）允許您根據路徑映射定義應包含哪個控制器的方法。我們現在包括所有這些，但您可以使用正則表達式等限制它（过滤）。
• 其中RequestHandlerSelectors是配置要扫描接口的方式
  basePackage:指定要扫描的包
  any():扫描全部
  none():不扫描
  withClassAnnotation：扫描类上的注解，参数是一个注解的反射对象
  withMethodAnnotation：扫描方法上的注解