Différences

Ci-dessous, les différences entre deux révisions de la page.

--- web:javascript:nodejs:swagger [2021/01/07 22:50] – [Tags] sgariepy
+++ web:javascript:nodejs:swagger [2022/02/02 00:42] (Version actuelle) – modification externe 127.0.0.1
@@ Ligne 1: / Ligne 1: @@
 ====== Swagger ======
-Incorporer Swagger avec JSDoc dans un projet TypeScript.
+Incorporer [[https://swagger.io/|Swagger]] avec JSDoc dans un projet TypeScript.
@@ Ligne 51: / Ligne 51: @@
-===== Exemple de JSDoc pour Swagger =====
+====== Exemple de JSDoc pour Swagger ======
 <code>
@@ Ligne 72: / Ligne 72: @@
-==== Exemple avec paramètres de request ====
+===== Exemple avec paramètres de request =====
 [[https://swagger.io/docs/specification/describing-parameters/|Documentation officielle - Describing Parameters]]
@@ Ligne 82: / Ligne 82: @@
    *     parameters:
    *     - in: header
-   *       name: x-auth-token
+   *       name: x-api-key
-   *       description: Auth Token
+   *       description: API Key
+   *       required: true
    *       schema:
    *         type: string
-   *       required: true
 </code>
@@ Ligne 124: / Ligne 124: @@
    *       description: Portfolio Id
 </code>
+===== Responses =====
+Response comme objet:
+<code>
+   *     responses:
+   *       200:
+   *         description: Authentication information
+   *         schema:
+   *           type: object
+   *           properties:
+   *             token:
+   *               type: string
+   *             accountIds:
+   *               type: array
+   *               items:
+   *                 type: string
+</code>
+<code>
+   *     responses:
+   *       200:
+   *         description: Application status
+   *         schema:
+   *           $ref: '#/definitions/ApplicationStatusResponse'
+   * definitions:
+   *   ApplicationStatusResponse:
+   *     properties:
+   *       name:
+   *         type: string
+   *       version:
+   *         type: string
+   *       env:
+   *         type: string
+   *       uptime:
+   *         type: integer
+</code>
+Réponse qui est une liste
+<code>
+   *     responses:
+   *       200:
+   *         description: Portfolio Information
+   *         schema:
+   *           type: 'array'
+   *           items:
+   *             $ref: '#/definitions/SerializedModel'
+</code>
+===== Schemas =====
+<code>
+/**
+ * @swagger
+ *  components:
+ *    schemas:
+ *      User:
+ *        type: object
+ *        required:
+ *          - name
+ *          - email
+ *        properties:
+ *          name:
+ *            type: string
+ *          email:
+ *            type: string
+ *            format: email
+ *            description: Email for the user, needs to be unique.
+ *        example:
+ *           name: Alexander
+ *           email: fake@email.com
+ */
+</code>
+Schema Reference:
+<code>
+ *         schema:
+ *           $ref: '#/definitions/CustomModel'
+</code>
+Schema avec enum:
+<code>
+          schema:
+            type: string
+            enum: [asc, desc]
+</code>
@@ Ligne 181: / Ligne 279: @@
+====== Sources ======
+  * [[https://levelup.gitconnected.com/swagger-time-to-document-that-express-api-you-built-9b8faaeae563|Swagger: Time to document that Express API you built!]]
+Option avec JSON Spec:
+  * [[https://sean-bradley.medium.com/add-swagger-ui-to-existing-nodejs-typescript-api-882ca7aded90|Your NodeJS TypeScript API is Nothing Without Swagger-UI]]
+Option avec YAML Spec:
+  * [[https://medium.com/swlh/the-easiest-way-to-start-using-swagger-in-node-js-54326864e74f|The Easiest Way To Start Using Swagger in Node.js]]
+Generateurs:
+  * [[https://github.com/lukeautry/tsoa|tsoa]]