SpringBoot集成Swagger構建api文檔的操作

更新時間：2020年12月03日 10:32:39 作者：都讓你們叫老了

這篇文章主要介紹了SpringBoot集成Swagger構建api文檔的操作，具有很好的參考價值，希望對大家有所幫助。一起跟隨小編過來看看吧

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

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

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

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

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

2、生成OpenAPI文檔

3、探索新的API功能

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

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

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

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

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

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

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

SpringBoot,Maven構建SwaggerAPI文檔

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

在這里就不過多進行介紹，只是說一下可能出現(xiàn)的問題：創(chuàng)建好項目之后目錄結構不對，只有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構建RESTful APIs")
    .description("myapp")
    .termsOfServiceUrl("http://blog.csdn.net/java_yes")
    .version("1.0").build();
  }
}

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

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

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 = "圖書詳細實體", 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 = "根據(jù)url的id來獲取詳細信息")
  @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我們已經配置完畢。此時訪問http://localhost:8080/swagger-ui.html#/greeting-controller。就可以看到Swagger-UI了。如下圖所示