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

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

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

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

1、執(zhí)行簡(jiǎn)單的API測(cè)試

2、生成OpenAPI文檔

3、探索新的API功能

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

1、Swagger可以整合到代碼中，在開(kāi)發(fā)時(shí)通過(guò)注解，編寫(xiě)注釋?zhuān)詣?dòng)生成API文檔。

2、將前端后臺(tái)分開(kāi)，不會(huì)有過(guò)分的依賴(lài)。

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

下面的兩點(diǎn)我還沒(méi)有進(jìn)行實(shí)踐：

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

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

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

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

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

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

第二步：創(chuàng)建類(lèi)以及配置pom.xml

1：配置pom.xml，添加依賴(lài)包：

第一個(gè)是API獲取的包，第二是官方給出的一個(gè)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類(lèi)

@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();
  }
}

這里有個(gè)特別需要注意的地方：

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

3：創(chuàng)建SpringBoot啟動(dòng)類(lèi)

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

4：創(chuàng)建controller

在這里我創(chuàng)建兩個(gè)controller，為了解釋@RequestMapping();這兩個(gè)Controller沒(méi)有任何實(shí)際意義，可以隨意創(chuàng)建，我只是為了測(cè)試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 | 通過(guò)書(shū)來(lái)測(cè)試swagger")
@RequestMapping(value = "/books")
public class BookController {

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

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

  @ApiOperation(value = "獲圖書(shū)細(xì)信息", notes = "根據(jù)url的id來(lái)獲取詳細(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 啟動(dòng)類(lèi)：

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

第三步：?jiǎn)?dòng)Swagger

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

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

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

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

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

這個(gè)就是我上面說(shuō)到的問(wèn)題：RequestHandlerSelectors.basePackage(“com.swagger”)

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

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

如果你只是單獨(dú)配置RequestHandlerSelectors.basePackage(“com.swagger”),或者RequestHandlerSelectors.basePackage(“com.swagger”)。那么就會(huì)顯示一個(gè)。

2：我配置的是RequestHandlerSelectors.basePackage(“com”)，但API還是只顯示一個(gè)，而且不顯示Controller直接訪問(wèn)地址也報(bào)錯(cuò)，如圖所示：

這個(gè)時(shí)候可能是SpringBoot的問(wèn)題了。他并沒(méi)有加載到你的另一個(gè)controller。

SpringBoot啟動(dòng)類(lèi)和Controller類(lèi)需要在同一包下，controller要在父類(lèi)包下。

這個(gè)時(shí)候有兩種解決方案：

1、將未加載的Conrtoller類(lèi)移動(dòng)到SpringBoot啟動(dòng)類(lèi)所在包?；蛘邔⑵浒臑閱?dòng)類(lèi)的子包。

2、如上述代碼，在啟動(dòng)類(lèi)上加注釋?zhuān)篅ComponentScan(basePackages={“com”})。該注釋會(huì)掃描所有com包下的controller并加載。

為什么我GreetingController沒(méi)有寫(xiě)rest方法。但是API中顯示了所有呢？

這個(gè)要用@RequestMapping();進(jìn)行解釋了。

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

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

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

最新評(píng)論