Swagger的使用方法詳解

一、Swagger簡介

Swagger是一種流行的API開發工具，它可以用來生成和管理RESTful服務的API文檔，並允許用戶通過UI界面來互動性地測試API請求和響應。Swagger提供了許多有用的功能，包括API模型的定義、文檔的生成、代碼生成、UI界面、測試、監控等。Swagger的目標是簡化API的設計、開發和維護，提升API的可讀性和可用性，增強API的開放性和互操作性。

二、Swagger的安裝和配置

Swagger可以在Java、JavaScript、Go、Python、C#等多種語言中使用，本文以Java為例介紹其安裝和配置過程。

1. Maven依賴

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

2. 開啟Swagger

在Spring Boot的主類中，添加@EnableSwagger2註解以開啟Swagger支持。

@SpringBootApplication
@EnableSwagger2
public class Application {
   ...
}

3. 配置Swagger

在application.properties或application.yml文件中，添加如下的Swagger配置：

swagger:
  title: My API
  description: My awesome API
  version: 1.0.0
  contact:
    name: My Team
    url: https://myteam.com
    email: team@myteam.com

這些配置將告訴Swagger如何在API文檔中顯示標題、描述、版本、聯繫人等信息。

三、使用Swagger生成API文檔

當Swagger在Spring Boot應用程序中啟用後，可以通過訪問http://localhost:8080/swagger-ui.html來獲取Swagger UI界面和API文檔。在Swagger UI中，可以看到所有控制器和操作的列表。

1. 創建API實例

在接下來的例子中，我們將展示如何創建一個簡單的API，並將其加入到Swagger文檔中。在src/main/java/com.example.demo/controller包中，創建一個名為PersonController的類，代碼如下：

@RestController
@RequestMapping("/person")
@Api(value="人員管理接口",tags={"PersonController"})
public class PersonController {

    @ApiOperation(value="獲取所有人員信息", notes="獲取所有人員信息")
    @GetMapping("/")
    public List getAll() {
        ...
    }

    @ApiOperation(value="根據ID獲取人員信息", notes="根據ID獲取人員信息")
    @ApiImplicitParam(name = "id", value = "人員ID", required = true, dataType = "Long", paramType = "path")
    @GetMapping("/{id}")
    public Person getById(@PathVariable long id) {
        ...
    }

    @ApiOperation(value="添加人員信息", notes="添加人員信息")
    @PostMapping("/")
    public void add(@RequestBody Person person) {
        ...
    }

    @ApiOperation(value="更新人員信息", notes="更新人員信息")
    @ApiImplicitParam(name = "id", value = "人員ID", required = true, dataType = "Long", paramType = "path")
    @PutMapping("/{id}")
    public void update(@PathVariable long id, @RequestBody Person person) {
        ...
    }

    @ApiOperation(value="刪除人員信息", notes="刪除人員信息")
    @ApiImplicitParam(name = "id", value = "人員ID", required = true, dataType = "Long", paramType = "path")
    @DeleteMapping("/{id}")
    public void delete(@PathVariable long id) {
        ...
    }

}

在上面的代碼中，我們使用了@RestController註解來聲明控制器，並使用@RequestMapping註解來定義控制器的路徑。我們還使用了@Api註解來為控制器定義一個名稱和一組標記。方法部分使用了@ApiOperation、@ApiImplicitParam等註解，來定義每個操作的名稱、說明、輸入、輸出等。這些註解將使Swagger API文檔具有更多的描述、關聯和結構。

2. 訪問Swagger UI界面

現在，我們已經創建了一個簡單的API，並為其添加了Swagger註解，接下來我們可以訪問http://localhost:8080/swagger-ui.html並查看生成的API文檔。在Swagger UI中，可以看到PersonController的相關操作，包括獲取所有人員信息、根據ID獲取人員信息、添加人員信息、更新人員信息和刪除人員信息。

3. 使用Swagger測試API

我們可以使用Swagger UI界面來測試創建的API。在Swagger UI中，點擊一個操作名稱，展開該操作的詳情。在其中，我們可以填寫測試請求參數、指定請求頭、查看響應結果等。

例如，我們可以在獲取所有人員信息的操作中，點擊「Try it out」按鈕，在「Response Body」中查看響應結果。

[
  {
    "id": 1,
    "name": "Alice",
    "age": 20
  },
  {
    "id": 2,
    "name": "Bob",
    "age": 30
  },
  {
    "id": 3,
    "name": "Charlie",
    "age": 40
  }
]

4. 下載API代碼

Swagger還可以生成API的代碼和客戶端庫。在Swagger UI中，點擊右上角的「Generate Client」按鈕，在彈出的對話框中選擇要生成的代碼語言、設置輸出目錄和選項等，點擊「Generate」按鈕，Swagger將為您生成代碼和客戶端庫。

四、Swagger的高級用法

1. 支持OAuth2.0認證

Swagger可以通過OAuth2.0認證方式來保護API，以避免未經授權的訪問。在Spring Security配置中，可以通過@EnableOAuth2註解啟用OAuth2認證，然後在Swagger配置中添加認證的相關參數，如下所示：

@Configuration
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .securitySchemes(Arrays.asList(securityScheme()))
                .securityContexts(Arrays.asList(securityContext()))
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("My API")
                .description("My awesome API")
                .version("1.0.0")
                .contact(new Contact("My Team", "https://myteam.com", "team@myteam.com"))
                .build();
    }

    private SecurityScheme securityScheme() {
        GrantType grantType = new AuthorizationCodeGrantBuilder()
                .tokenEndpoint(new TokenEndpointBuilder().url("http://localhost:8080/oauth/token").build())
                .tokenRequestEndpoint(
                        new TokenRequestEndpointBuilder().url("http://localhost:8080/oauth/authorize").build())
                .build();

        SecurityScheme oauth = new OAuthBuilder().name("spring_oauth")
                .grantTypes(Arrays.asList(grantType))
                .scopes(Arrays.asList(scopes()))
                .build();
        return oauth;
    }

    private SecurityContext securityContext() {
        return SecurityContext.builder()
                .securityReferences(Arrays.asList(new SecurityReference("spring_oauth", scopes()))).forPaths(PathSelectors.any())
                .build();
    }

    private AuthorizationScope[] scopes() {
        AuthorizationScope[] scopes = { 
                new AuthorizationScope("read", "for read operations"),
                new AuthorizationScope("write", "for write operations") };
        return scopes;
    }

}

2. 支持多國語言

Swagger可以用來生成多國語言的API文檔。在Swagger配置中，可以添加參數包含多國語言文本，例如：

@Configuration
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("My API")
                .description("My awesome API")
                .version("1.0.0")
                .contact(new Contact("My Team", "https://myteam.com", "team@myteam.com"))
                .termsOfServiceUrl("https://myteam.com/terms")
                .license("Apache 2.0")
                .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")
                .extensions(Collections.singletonList(new StringVendorExtension("language", "en")))
                .build();
    }

}

3. 支持上傳下載文件

Swagger支持在API中上傳下載文件。在操作參數中，使用@ApiParam註解來定義文件上傳參數類型：

@ApiOperation(value="上傳文件", notes="上傳文件")
@PostMapping("/upload")
public void upload(@RequestParam("file") @ApiParam(name = "file", value = "上傳的文件") MultipartFile file) {
    ...
}

@ApiOperation(value="下載文件", notes="下載文件")
@PostMapping("/download")
public void download(@RequestParam("path") @ApiParam(name = "path", value = "文件路徑") String path, HttpServletResponse response) {
    ...
}

4. 支持API版本控制

Swagger支持對API進行版本控制。在配置中，指定API的版本號即可：

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    private static final String[] PRODUCES_AND_CONSUMES = { MediaType.APPLICATION_JSON_VALUE };

    @Bean
    public Docket apiV1() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("v1")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
                .paths(PathSelectors.ant("/v1/**"))
                .build()
                .apiInfo(apiInfo())
                .produces(Arrays.asList(PRODUCES_AND_CONSUMES))
                .consumes(Arrays.asList(PRODUCES_AND_CONSUMES));
    }

    @Bean
    public Docket apiV2() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("v2")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
                .paths(PathSelectors.ant("/v2/**"))
                .build()
                .apiInfo(apiInfo())
                .produces(Arrays.asList(PRODUCES_AND_CONSUMES))
                .consumes(Arrays.asList(PRODUCES_AND_CONSUMES));
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("My API")
                .description("My awesome API")
                .version("1.0.0")
                .contact(new Contact("My Team", "https://myteam.com", "team@myteam.com"))
                .build();
    }

}

5. 支持分組管理API

Swagger支持將API分組管理。在配置中，使用Docket的groupName來指定API所屬分組，例如：

@Configuration

@EnableSwagger2

public class SwaggerConfig {
 private static final String[] PRODUCES_AND_CONSUMES = { MediaType.APPLICATION_JSON_VALUE };
 @Bean
 public Docket apiA() {
 return new Docket(DocumentationType.SWAGGER_2)
 .groupName("Group A")
 .select()
 .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller.a"))
 .paths(PathSelectors.any())
 .build()
 .apiInfo(apiInfo())
 .produces(Arrays.asList(PRODUCES_AND_CONSUMES))
 .consumes(Arrays.asList(PRODUCES_AND_CONSUMES));
 }
 @Bean
 public Docket apiB() {
 return new Docket(DocumentationType.SWAGGER_2)
 .groupName("Group B")
 .select()
 .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller.b"))
 .paths(PathSelectors.any())
 .build()
 .apiInfo(apiInfo())
 .produces(Arrays.asList(PRODUCES_AND_CONSUMES))
 .consumes(Arrays.asList(PRODUCES_AND_CONSUMES));
 }
 private ApiInfo apiInfo() {
 return new ApiInfoBuilder()
 .title("My API")
 .description("My awesome API")
原創文章，作者：ONMSR，如若轉載，請註明出處：https://www.506064.com/zh-hk/n/361680.html