最近在做項目的時候，一直用一個叫做API的東西，controller注解我會寫，這個東西我也會用，但是我確實不知道這個東西是個什么，有點神奇。關(guān)鍵還坑了我一次，他的注解會影響到代碼的運行，不光是起到注解的作用。所以我就研究了一下。

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

根據(jù)官網(wǎng)的介紹：

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

1、執(zhí)行簡單的API測試

2、生成OpenAPI文檔

3、探索新的API功能

我的理解Swagger是一個規(guī)范和完整的框架，用于生成、描述、調(diào)用和可視化RESTful風(fēng)格的Web服務(wù)。簡單來說，Swagger是一個功能強大的接口管理工具，并且提供了多種編程語言的前后端分離解決方案。根據(jù)我的使用，當(dāng)然我只是最簡單的使用，我感覺Swagger有以下幾個優(yōu)點：

1、Swagger可以整合到代碼中，在開發(fā)時通過注解，編寫注釋，自動生成API文檔。

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

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

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

1、支持Json和yaml來編寫API文檔，并且支持導(dǎo)出為json、yaml、markdown等格式

2、如果編寫好了API了，可以自動生成相應(yīng)的SDK，沒錯，可能你的API接口代碼還沒有開始寫，它就能幫你制作相應(yīng)的SDK了，而且支持幾乎所有主流編程語言的SDK。

SpringBoot,Maven構(gòu)建SwaggerAPI文檔

第一步：創(chuàng)建SpringBoot Web項目

在這里就不過多進行介紹，只是說一下可能出現(xiàn)的問題：創(chuàng)建好項目之后目錄結(jié)構(gòu)不對，只有src/main/resources文件夾。下圖所示

這時候只需要將JDK版本升級到你安裝的版本就可以，其他文件夾就可以顯現(xiàn)出來：

第二步：創(chuàng)建類以及配置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，創(chuàng)建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構(gòu)建RESTful APIs")
    .description("myapp")
    .termsOfServiceUrl("http://blog.csdn.net/java_yes")
    .version("1.0").build();
  }
}

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

RequestHandlerSelectors.basePackage(“com.swagger”)，這是掃描注解的配置，即你的API接口位置。文章最后我會做總結(jié)。

3：創(chuàng)建SpringBoot啟動類

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

4：創(chuàng)建controller

在這里我創(chuàng)建兩個controller，為了解釋@RequestMapping();這兩個Controller沒有任何實際意義，可以隨意創(chuàng)建，我只是為了測試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="創(chuàng)建圖書", notes="創(chuàng)建圖書")
  @ApiImplicitParam(name = "book", value = "圖書詳細(xì)實體", required = true, dataType = "Book")
  @RequestMapping(value="", method=RequestMethod.POST)
  public String postBook(@RequestBody Book book) {
    books.put(book.getId(), book);
    return "success";
  }

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

5：創(chuàng)建SpringBoot 啟動類：

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

第三步：啟動Swagger

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

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

坑?。。?！我在配置過程中出現(xiàn)的錯誤；

我先發(fā)一下我的文件結(jié)構(gòu)：

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

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

這個地方配置的是你swagger要加載的接口所在的包名。會去掃秒這個包下的所有Controller。大家看我的文件結(jié)構(gòu)。

如果你配置的是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啟動類所在包?；蛘邔⑵浒臑閱宇惖淖影?/p>

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

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

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

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

2、@RequestMapping(value = “/swagger”,method = RequestMethod.POST)，當(dāng)你自己設(shè)置mathod的時候，就會只創(chuàng)建你設(shè)置的method。

以上這篇SpringBoot集成Swagger構(gòu)建api文檔的操作就是小編分享給大家的全部內(nèi)容了，希望能給大家一個參考，也希望大家多多支持腳本之家。