Swagger を使用して API ドキュメントを生成するにはどうすればよいですか?

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

Swagger とは何ですか?

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

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

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

ステップ 1: Swagger の構成

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

Java Spring Boot プロジェクトで Swagger API を構成するには、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 のバージョン番号を表します。構成ファイル 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 = "根据url的id来获取用户详细信息")
@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 ドキュメントを自動的に構築します。

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

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

概要

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

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