web-dev-qa-db-ja.com

SwaggerをExpressアプリケーションと統合する方法

私はいつも、ノードサイドサービスを適切なドキュメントを使用して他のチームと共有していました。このドキュメントに基づいて、彼らは私のサービスを使用します。

これに関して、私が他の人と話したとき。彼は私にswaggerを使うように提案しました。しかし、アプリケーションに統合する方法がわかりません。

私のアプリケーションはExpressで書かれています。私はグーグルでこれを検索しました、私は良いチュートリアルを見つけられませんでした。誰かがすでに実装している場合は、私に提案できますか。どのモジュールがどのように優れているか。

また、知りたいのは、swaggerプラットフォームをサポートするNodeのような他のライブラリです。

ありがとう

node.jsexpressswaggerswagger-ui
8
grandhi

Expressモジュールを使用してExpressAPIを文書化した経験があります（swagger-node-express）。また、手動のSwaggerJSONドキュメントを使用してExpressAPIを文書化した経験もあります。

Swaggerドキュメントのモジュールに縛られないことをお勧めします。ほとんどのモジュール（特にswagger-node-express）では、ドキュメントを処理するためにExpressコードを別の方法で記述する必要があります。 JSONを使用してSwaggerドキュメントを手動で作成する場合、Expressを作成し、ドキュメントをルーティングから切り離すことができます。

Swagger UI を使用して、ドキュメントのスタイルを設定し、Webページに追加します。

開始時に使用できるリソースは次のとおりです。

Swagger Editor --Swaggerドキュメントを編集して、変更をライブアップデートで確認します
Swagger Docs -JSONのSwagger仕様
チュートリアル -これは古いバージョンのSwaggerを使用しています。必ずチェックしてください Migrating Swagger 最新バージョンにアップグレードしてください

また、手動とモジュールベースのSwaggerドキュメント生成の違いを説明するこの回答を見てください-> [〜＃〜] here [〜＃〜] 。

8
Mike

最近、swaggerを使用してAPIドキュメントを実装することに遭遇しました。 「swagger-ui-express」npmモジュールを使用して実装しました。実行時にJSONを作成しました。つまり、サーバーの実行が開始されたら、データをキャプチャし、以下のファイルのようなSwagger仕様に従って変更しました。

https://editor.swagger.io/ ここでは、JSONでSwaggerの仕様を確認できます。

「swagger-ui-express」モジュールが必要で、JSONを作成し、以下のようにファイルをswaggeruiにフィードします。

const swaggerUi = require('swagger-ui-express');
const swaggerDocument = require('./swagger.json');

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));
1
Mythili

私はあなたの質問が完全には明確ではありませんが、あなたはこのようなものを探していると思います： swagger-tools

私はこのモジュールを使用し、それは素晴らしかったです。作成したExpressappにバインドできるミドルウェアを公開します。たとえば、サービスが文書化されていて、その文書が Swagger準拠 である場合、その文書をミドルウェアに渡すことができます。ミドルウェアは、ドキュメントにある定義に基づいてリクエストハンドラを接続したり、ドキュメントにある定義に対してリクエストを検証したりするなど、いくつかのすばらしいことを行います。

それは素晴らしい チュートリアル を持っており、セットアップを取得するのは非常に簡単です。これがお役に立てば幸いです。あなたが探していたものに沿ったものです。

1
Michael Jonas

Expressアプリでライブドキュメントが自動的に提供されるため、このようなスワッガーを使用します。

  • API仕様：OpenAPI（Swagger）仕様を使用してコードをYAML形式で文書化します。これは swagger-jsdoc のおかげで達成されます。
  • ライブドキュメント：swagger-ui-express "Expressアプリにミドルウェアを追加して、 SwaggerドキュメントにバインドされたSwaggerUI。これは、アプリ内からホストされるAPIの生きたドキュメントとして機能します。 "

次に、ドキュメントを配置するルートを作成するだけです。

const swaggerSpec = swaggerJSDoc({
  swaggerDefinition: {
    info: {
      title: 'My App API',
      version: '1.0.0'
    }
  },
  apis: ['./routes/index.js']
});

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));

swagger-ui-expresshanの組み込みサポートswagger-jsdocをご覧ください-）。詳細については、 swagger-ui-express および swagger-jsdocs入門ドキュメント をお読みください。

API仕様の例：

swagger-jsdocs入門ドキュメント から取得。

/**
 * @swagger
 * /login:
 *   post:
 *     description: Login to the application
 *     produces:
 *       - application/json
 *     parameters:
 *       - name: username
 *         description: Username to use for login.
 *         in: formData
 *         required: true
 *         type: string
 *       - name: password
 *         description: User's password.
 *         in: formData
 *         required: true
 *         type: string
 *     responses:
 *       200:
 *         description: login
 */
app.post('/login', function(req, res) {
  res.json(req.body);
});

生成されたドキュメントの例：

それらはほとんど Swagger UIの例 のようになります。

0
Martin Schaer