最近在做專案的時候，一直用一個叫做API的東西，controller註解我會寫，這個東西我也會用，但是我確實不知道這個東西是個什麼，有點神奇。關鍵還坑了我一次，他的註解會影響到程式碼的執行，不光是起到註解的作用。所以我就研究了一下。

Swagger是什麼：THE WORLD'S MOST POPULAR API TOOLING

根據官網的介紹：

Swagger Inspector：測試API和生成OpenAPI的開發工具。Swagger Inspector的建立是為了解決開發者的三個主要目標。

1、執行簡單的API測試

2、生成OpenAPI文件

3、探索新的API功能

我的理解Swagger是一個規範和完整的框架，用於生成、描述、呼叫和視覺化RESTful風格的Web服務。簡單來說，Swagger是一個功能強大的介面管理工具，並且提供了多種程式語言的前後端分離解決方案。根據我的使用，當然我只是最簡單的使用，我感覺Swagger有以下幾個優點：

1、Swagger可以整合到程式碼中，在開發時通過註解，編寫註釋，自動生成API文件。

2、將前端後臺分開，不會有過分的依賴。

3、介面清晰，無論是editor的實時展示還是ui的展示都十分人性化，如果自己僅僅用markdown來編寫，又要糾結該如何展現，十分痛苦。

下面的兩點我還沒有進行實踐：

1、支援Json和yaml來編寫API文件，並且支援匯出為json、yaml、markdown等格式

2、如果編寫好了API了，可以自動生成相應的SDK，沒錯，可能你的API介面程式碼還沒有開始寫，它就能幫你製作相應的SDK了，而且支援幾乎所有主流程式語言的SDK。

SpringBoot,Maven構建SwaggerAPI文件

第一步：建立SpringBoot Web專案

在這裡就不過多進行介紹，只是說一下可能出現的問題：建立好專案之後目錄結構不對，只有src/main/resources資料夾。下圖所示

這時候只需要將JDK版本升級到你安裝的版本就可以，其他資料夾就可以顯現出來：

第二步：建立類以及配置pom.xml

1：配置pom.xml，新增依賴包：

第一個是API獲取的包，第二是官方給出的一個ui介面。三和四是spring boot 需要的jar包。

  <dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.6.1</version>
  </dependency>

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

  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
  </dependency>

  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-test</artifactId>
    <scope>test</scope>
  </dependency>

2：配置Swagger，建立SwaggerConfig.java類

@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
    return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
      .select()
      .apis(RequestHandlerSelectors.basePackage("com"))
      .paths(PathSelectors.any()).build();
}


private ApiInfo apiInfo() {
  return new ApiInfoBuilder()
    .title("Spring Boot中使用Swagger2構建RESTful APIs")
    .description("myapp")
    .termsOfServiceUrl("http://blog.csdn.net/java_yes")
    .version("1.0").build();
  }
}

這裡有個特別需要注意的地方：

RequestHandlerSelectors.basePackage(“com.swagger”)，這是掃描註解的配置，即你的API介面位置。文章最後我會做總結。

3：建立SpringBoot啟動類

@SpringBootApplication
public class Application {
  public static void main(String[] args) {
    SpringApplication.run(Application.class,args);
  }
}

4：建立controller

在這裡我建立兩個controller，為了解釋@RequestMapping();這兩個Controller沒有任何實際意義，可以隨意建立，我只是為了測試SwaggerAPI

GreetingController

@RestController
@RequestMapping(value = "/test")
public class GreetingController {
  private static final String template = "Hello,%s!";
  private final AtomicLong counter = new AtomicLong();

  @RequestMapping(value = "/swagger")
  //@RequestMapping("/swagger")
  //@RequestMapping(value = "/swagger",method = RequestMethod.POST)
  public Greeting greeting(@RequestParam(value = "name",defaultValue = "World") String name) {
    return new Greeting(counter.incrementAndGet(),String.format(template,name));
  }
}

BookController

@RestController
@Api(tags = "BookController",description = "BookController | 通過書來測試swagger")
@RequestMapping(value = "/books")
public class BookController {

  Map<Long,Book> books = Collections.synchronizedMap(new HashMap<Long,Book>());

  @ApiOperation(value="建立圖書",notes="建立圖書")
  @ApiImplicitParam(name = "book",value = "圖書詳細實體",required = true,dataType = "Book")
  @RequestMapping(value="",method=RequestMethod.POST)
  public String postBook(@RequestBody Book book) {
    books.put(book.getId(),book);
    return "success";
  }

  @ApiOperation(value = "獲圖書細資訊",notes = "根據url的id來獲取詳細資訊")
  @ApiImplicitParam(name = "id",value = "ID",dataType = "Long",paramType = "path")
  @RequestMapping(value = "/{id}",method = RequestMethod.GET)
  public Book getBook(@PathVariable Long id) {
    return books.get(id);
  }
}

5：建立SpringBoot 啟動類：

@SpringBootApplication
@ComponentScan(basePackages={"com"}) 
public class Application {
  public static void main(String[] args) {
    SpringApplication.run(Application.class,args);
  }
}

第三步：啟動Swagger

OK，到此為止，整個Swagger我們已經配置完畢。此時訪問http://localhost:8080/swagger-ui.html#/greeting-controller。就可以看到Swagger-UI了。如下圖所示

同樣，根據@RequestMapping()的路徑我們可以進行訪問，再API中進行測試一樣。這裡我就進行演示。

坑！！！！我在配置過程中出現的錯誤；

我先發一下我的檔案結構：

1：什麼都配置了，但是API什麼都不顯示。如圖所示：

這個就是我上面說到的問題：RequestHandlerSelectors.basePackage(“com.swagger”)

這個地方配置的是你swagger要載入的介面所在的包名。會去掃秒這個包下的所有Controller。大家看我的檔案結構。

如果你配置的是RequestHandlerSelectors.basePackage(“com”)，那麼就會掃描所有com包下的Controller，包括com.swagger;以及com.controller。效果就是這樣：

如果你只是單獨配置RequestHandlerSelectors.basePackage(“com.swagger”),或者RequestHandlerSelectors.basePackage(“com.swagger”)。那麼就會顯示一個。

2：我配置的是RequestHandlerSelectors.basePackage(“com”)，但API還是隻顯示一個，而且不顯示Controller直接訪問地址也報錯，如圖所示：

這個時候可能是SpringBoot的問題了。他並沒有載入到你的另一個controller。

SpringBoot啟動類和Controller類需要在同一包下，controller要在父類包下。

這個時候有兩種解決方案：

1、將未載入的Conrtoller類移動到SpringBoot啟動類所在包。或者將其包名改為啟動類的子包。

2、如上述程式碼，在啟動類上加註釋：@ComponentScan(basePackages={“com”})。該註釋會掃描所有com包下的controller並載入。

為什麼我GreetingController沒有寫rest方法。但是API中顯示了所有呢？

這個要用@RequestMapping();進行解釋了。

1、@RequestMapping(value = “/swagger”)或者@RequestMapping(“/swagger”)這麼寫的時候，就會載入所有method。

2、@RequestMapping(value = “/swagger”,method = RequestMethod.POST)，當你自己設定mathod的時候，就會只建立你設定的method。

以上這篇SpringBoot整合Swagger構建api文件的操作就是小編分享給大家的全部內容了，希望能給大家一個參考，也希望大家多多支援我們。