什么是Swagger？

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

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

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

• 執(zhí)行簡單的API測試
• 生成OpenAPI文檔
• 探索新的API功能

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

Swagger可以整合到代碼中，在開發(fā)時通過注解，編寫注釋，自動生成API文檔。
將前端后臺分開，不會有過分的依賴。

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

構(gòu)建項目

step1.導(dǎo)入依賴

 <!--swagger服務(wù)api構(gòu)建個性包-->
 <dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger2</artifactId>
  <version>2.6.1</version>
 </dependency>
 <!--swagger ui界面-->
 <dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger-ui</artifactId>
  <version>2.6.1</version>
 </dependency>
 <!--springboot web服務(wù)-->
 <dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-web</artifactId>
 </dependency>
 <!--springboot單元測試-->
 <dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-test</artifactId>
  <scope>test</scope>
 </dependency>

step2.編寫swagger配置類

想要使用swagger功能必須提供配置類，主要配置ui界面信息，以及配置掃描位置，swagger會根據(jù)配置的路徑掃描所有的服務(wù)生成api。

其中核心RequestHandlerSelectors.basePackage("com.simple.spring.boot.controller"),在這里配置我們的需要的掃描包位置。

@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
  return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
   .select()
   .apis(RequestHandlerSelectors.basePackage("com.simple.spring.boot.controller"))
   .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/SimpleWu")
  .version("1.0").build();
 }
}

step3.編寫springboot啟動類

@ComponentScan(basePackages={"com.simple.spring.boot.controller"}) 也是需要配置掃描路徑。

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

step4.創(chuàng)建前端控制器

@RestController
@Api(tags = "swgger測試服務(wù)", description = "swgger測試服務(wù)")
@RequestMapping(value = "/simple/wu")
public class TestController {

 @ApiOperation(value="測試POST方法", notes="測試POST方法")
 @ApiImplicitParam(name = "令牌", value = "ID", required = true, dataType = "token")
 @RequestMapping(value="hello", method=RequestMethod.POST)
 public String post(@RequestBody String token) {
  books.put(book.getId(), book);
  return "success";
 }
}

• @Api(tags = "swgger測試服務(wù)", description = "swgger測試服務(wù)") 指定某個類提供服務(wù)的名字
• @ApiOperation(value="測試POST方法", notes="測試POST方法") 指定某個請求的名字
• @ApiImplicitParam(name = "令牌", value = "token", required = true, dataType = "String")指定名字對應(yīng)參數(shù)為令牌，以及對應(yīng)參數(shù)字段token，required = true代表這個參數(shù)為必填參數(shù)，dataType 代表數(shù)據(jù)類型。

step5.啟動服務(wù)

從上面的代碼中我們指定請求為POST在UI界面上我們會看到一個服務(wù)名字為swgger測試服務(wù)的大類點擊進去后可以看到里面所擁有的請求，如果指定這個請求的類型那么無法進行單元測試，指定后我們會看到一個請求名字叫做測試POST方法的請求并且需要填入必填參數(shù)token來完成我們的單元測試。

我們可以直接通過SwaggerApplication類來運行main方法來進行服務(wù)，端口號默認為8080.

swagger地址：http://localhost:8080/swagger-ui.html 只需要在地址后面加上swagger-ui.html即可訪問

我們訪問這個位置即可看到UI界面，界面簡潔并且容易上手，我這邊就不截圖了。

step.總結(jié)

swagger官方文檔:https://www.baeldung.com/swagger-2-documentation-for-spring-rest-api

swagger的一個最大的優(yōu)點是能實時同步api與文檔。

在項目開發(fā)過程中，發(fā)生過多次：修改代碼但是沒有更新文檔，前端還是按照老舊的文檔進行開發(fā)，在聯(lián)調(diào)過程中才發(fā)現(xiàn)問題的情況（當(dāng)然依據(jù)開閉原則，對接口的修改是不允許的，但是在項目不穩(wěn)定階段，這種情況很難避免）。

總結(jié)

以上就是這篇文章的全部內(nèi)容了，希望本文的內(nèi)容對大家的學(xué)習(xí)或者工作具有一定的參考學(xué)習(xí)價值，如果有疑問大家可以留言交流，謝謝大家對腳本之家的支持。

最新評論