PHP 開発: Swagger を使用して API ドキュメントを保守する方法
- WBOYオリジナル
- 2023-06-15 09:37:17972ブラウズ
インターネットの急速な発展に伴い、Web API はオープン アプリケーションをサポートする中核になりました。 API のスケーラビリティと再利用性により、API は異なるシステム間のデータ交換とコラボレーションのための重要なツールになります。ただし、開発者はよく「API ドキュメントを管理し、API の信頼性を確保するにはどうすればよいですか?」という共通の質問に直面します。
Swagger は、API 設計、ドキュメント、テスト、展開のための完全なソリューションを提供するオープン ソース フレームワークです。この記事では、Swagger を使用して API ドキュメントを管理し、既存の API をより適切に管理および保守する方法について説明します。
1. Swagger の基本概念
Swagger は、API を記述する JSON または YAML 仕様ファイルを通じて API を作成し、文書化します。このファイルは Swagger 仕様と呼ばれます。
Swagger 仕様ファイルには次の概念が含まれています。
- パス: API パスはリソースの識別子です。たとえば、/users はすべてのユーザーを表し、/users/{id} はユーザーを表します。
- メソッド: GET、PUT、POST、DELETE、HEAD などの HTTP メソッド。
- パラメータ: リクエストパラメータ (HTTP リクエスト本文、URL パス、クエリ文字列パラメータ、あるいはその両方)。
- 応答: HTTP 応答の構造、ステータス コード、および応答本文 (HTTP 応答本文) のタイプ。
- モデル: データ転送オブジェクト (DTO) と応答オブジェクトの構造。
- タグ: API リソースを論理的にグループ化し、読みやすくします。
2. Swagger の使用
- Swagger UI のインストール
Swagger UI は、Swagger 仕様ファイルを可能にするオープン ソース ツールです。インターフェイスに表示されます。その主な目的は、明確で対話型のドキュメントを提供し、API のテストとデバッグを可能にすることです。
次のコマンドを使用して Swagger UI をインストールします:
npm install swagger-ui-dist
- Swagger 仕様ファイルを作成します
Swagger 仕様ファイルを作成してパスとメソッドを説明しますAPI、パラメータ、レスポンス、その他の情報。
以下は例です:
swagger: '2.0'
info:
title: User API Root
version: 1.0.0
paths:
/users:
get:
tags:
- users
description: Returns all users
produces:
- application/json
responses:
200:
description: A list of user names
schema:
type: object
properties:
id:
type: integer
example: 123
name:
type: string
example: John Doeこの例では、API パス「/users」と GET メソッドを定義し、「id」と「name」の配列を含む JSON を返します。応答してオブジェクト。
- Swagger UI の統合
Swagger UI を Web アプリケーションに統合して、Swagger 仕様ファイルを表示します。次の HTML コードを Web ページに追加します。
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>Swagger UI</title>
<link rel="stylesheet" type="text/css" href="./node_modules/swagger-ui-dist/swagger-ui.css">
</head>
<body>
<div id="swagger-ui"></div>
<script src="./node_modules/swagger-ui-dist/swagger-ui-bundle.js"></script>
<script>
window.onload = function() {
SwaggerUIBundle({
url: "https://api.example.com/swagger",
dom_id: '#swagger-ui',
deepLinking: true,
presets: [
SwaggerUIBundle.presets.apis,
SwaggerUIBundle.SwaggerUIStandalonePreset
],
plugins: [
SwaggerUIBundle.plugins.DownloadUrl
],
layout: "StandaloneLayout"
})
}
</script>
</body>
</html>この例では、Swagger UI を HTML ファイルにロードし、Swagger 仕様ファイルの URL アドレスを SwaggerUIBundle に渡して、API ドキュメントを表示します。
- API のテストとデバッグ
Swagger UI を使用して、Web アプリケーションの API をテストおよびデバッグします。
Swagger UI を通じて、次のことができます。
- インターフェイスのドキュメントを表示します。
- テストを自動化し、API の応答結果を確認します。
- API をデバッグし、コード スニペットを生成します。
概要
Swagger は、API 設計、ドキュメント、テスト、展開のための完全なソリューションを開発者に提供できる優れたフレームワークです。 Swagger を使用すると、既存の API をより適切に管理および保守できます。これは、集中開発モデルにおける最良の方法の 1 つでもあります。
以上がPHP 開発: Swagger を使用して API ドキュメントを保守する方法の詳細内容です。詳細については、PHP 中国語 Web サイトの他の関連記事を参照してください。