Web アプリケーションの急速な開発に伴い、API ドキュメントの重要性がますます高まっています。 API ドキュメントは、開発者が API の使用方法とパラメーターを理解できるように設(shè)計されており、時間とリソースの無駄を削減します。ただし、API ドキュメントを手動で作成するのは面倒で時間がかかるため、現(xiàn)時點(diǎn)では、Swagger は開発者にとって強(qiáng)力なツールとなっています。 Swagger は、読みやすく対話型の API ドキュメントを自動的に生成できる人気の API ドキュメント ツールです。この記事では、Swagger を使用して API ドキュメントを自動生成する方法を紹介しました。

Swagger とは何ですか?

Swagger は、開発者が RESTful Web サービスを構(gòu)築、設(shè)計、記述、利用するのに役立つオープン ソース ツールのセットです。 Swagger を使用すると、YAML または JSON 形式を使用して API 操作を説明する API ドキュメントを作成し、読みやすく操作しやすいインターフェイス ドキュメントを生成できます。

Swagger は、Java、C#、Python、Ruby などの複數(shù)のプログラミング言語とフレームワークをサポートしています。 Spring、Express、Django など、多くの既存の API フレームワークと統(tǒng)合することもできます。

Swagger を使用して API ドキュメントを生成するには、まず Swagger UI をインストールする必要があります。 Swagger UI は、API から獨(dú)立しており、Swagger 仕様に従っている対話型の API ドキュメント Web サイトです。 API ドキュメントを視覚化するための美しいインターフェイスを提供し、API 呼び出しの自動試行をサポートします。

ステップ 1: Swagger の構(gòu)成

Swagger を使用するには、まず Swagger パッケージをダウンロードする必要があります。このパッケージは、Swagger Web サイトから入手するか、依存関係マネージャーを使用してダウンロードできます。

Java Spring Boot プロジェクトで Swagger API を構(gòu)成するには、Maven 依存関係に次の Swagger 依存関係を追加する必要があります:

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>${springfox-swagger2.version}</version>
</dependency>
 
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>${springfox-swagger-ui.version}</version>
</dependency>

その中に ${springfox-swagger2.version} と $ {springfox-swagger-ui .version} は Swagger のバージョン番號を表します。構(gòu)成ファイル application.properties で Swagger を有効にします:

#開啟swagger
swagger.enabled = true

ステップ 2: Swagger 注釈を作成する

Swagger は、注釈を使用して API の操作とパラメーターを記述します。 Swagger がドキュメントを正しく解析して生成し、Swagger UI に表示できるように、API コントローラー クラスとそのメソッドの先頭に Swagger アノテーションを追加します。

以下はアノテーションのサンプルです:

1. @Api: API の説明情報を追加するために使用されます

@Api(value="User",tags={"User 操作接口"})
@Controller
@RequestMapping("/users")
public class UserController {
    // ...
}

2. @ApiOperation: 使用されます追加する API オペレーションの説明情報

@ApiOperation(value = "獲取用戶列表", notes = "")
@GetMapping(value = "/list")
public Result getUserList() {
    List<User> userList = userService.listUser();
    return Result.success(userList);
}

3. @ApiParam: API オペレーション パラメーターの追加に使用される説明情報

@ApiOperation(value = "獲取用戶信息", notes = "根據(jù)url的id來獲取用戶詳細(xì)信息")
@GetMapping(value = "/{id}")
public Result getUserById(@ApiParam(value = "用戶ID", required = true) @PathVariable Long id) {
    User user = userService.getUserById(id);
    return Result.success(user);
}

ステップ 3: アプリケーションを起動し、Swagger にアクセスしますUI

Swagger アノテーションの作成が完了したら、ブラウザを使用して Swagger UI のアドレスを開きます。 API に基づいてビジュアルな API ドキュメントを自動的に構(gòu)築します。

Swagger UI のデフォルトのアドレスは次のとおりです: http://localhost:8080/swagger-ui.html

Swagger UI インターフェイスでは、API およびさまざまな API の概要を確認(rèn)できます。インターフェース、リクエストおよびレスポンスパラメータ、テストコードなどの説明。これは、開発者が API をよりよく理解し、使用するのに役立ちます。

概要

Swagger は、読みやすく操作しやすい API ドキュメントを自動的に生成できる強(qiáng)力な API ドキュメント ツールです。 Swagger を使用すると、API 開発の効率と品質(zhì)が向上し、API ドキュメントを手動で作成するために必要な時間とリソースが削減されます。上記の手順に従うことで、Swagger の使用を簡単に開始して API ドキュメントを自動的に生成できます。

以上がSwagger を使用して API ドキュメントを生成するにはどうすればよいですか?の詳細(xì)內(nèi)容です。詳細(xì)については、PHP 中國語 Web サイトの他の関連記事を參照してください。