Wiki SGY.io

Outils pour utilisateurs

Outils du site

Piste :
web:javascript:nodejs:swagger

Différences

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

Lien vers cette vue comparative

Les deux révisions précédentesRévision précédente
Prochaine révision		Révision précédente
web:javascript:nodejs:swagger [2021/01/07 22:37] – [Exemple avec paramètres de request] sgariepyweb:javascript:nodejs:swagger [2022/02/02 00:42] (Version actuelle) – modification externe 127.0.0.1
Ligne 1: Ligne 1:
 ====== Swagger ====== ====== 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> <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]] [[https://swagger.io/docs/specification/describing-parameters/|Documentation officielle - Describing Parameters]]
Ligne 82: Ligne 82:
    *     parameters:    *     parameters:
    *     - in: header    *     - in: header
-   *       name: x-auth-token +   *       name: x-api-key 
-   *       description: Auth Token+   *       description: API Key 
 +   *       required: true
    *       schema:    *       schema:
    *         type: string    *         type: string
-   *       required: true 
 </code> </code>
  
Ligne 95: Ligne 95:
    *     parameters:    *     parameters:
    *     - in: body    *     - in: body
 +   *       name: Portfolio information
 +   *       description: Provide needed Portfolio Information to create it
 +   *       required: true
    *       schema:    *       schema:
    *         type: object    *         type: object
    *         properties:    *         properties:
-   *           someStringToSend:+   *           name:
    *             type: string    *             type: string
    *             required: true    *             required: true
-   *           otherProperty:+   *           description:
    *             type: string    *             type: string
-   *             required: true+   *             required: false
 </code> </code>
  
 +Path:
  
  
  
 +<code>
 +   * /portfolios/:portfolioId:
 +   * 
 +   * ...
 +   * 
 +   *     - in: path
 +   *       name: portfolio id
 +   *       type: string
 +   *       required: true
 +   *       description: Portfolio Id
 +</code>
 +
 +
 +===== Responses =====
 +
 +Response comme objet:
  
 <code> <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> </code>
 +
 +Réponse qui est une liste
  
  
 <code> <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> </code>
  
 +
 +Schema Reference:
  
 <code> <code>
 + *         schema:
 + *           $ref: '#/definitions/CustomModel'
 +</code>
 +
 +Schema avec enum:
 +
 +
 +<code>
 +          schema:
 +            type: string
 +            enum: [asc, desc]
  
 </code> </code>
  
  
 +
 +===== Tags =====
 +
 +<code>
 +/**
 + * @swagger
 + * tags:
 + *   name: Users
 + *   description: User management
 + */
 +</code>
 +
 +<code>
 +/**
 + * @swagger
 + *
 + *  tags:
 + *    - name: pets
 + *      description: Everything about your Pets
 + *      externalDocs:
 + *        url: http://docs.my-api.com/pet-operations.htm
 + *    - name: store
 + *      description: Access to Petstore orders
 + *      externalDocs:
 + *        url: http://docs.my-api.com/store-orders.htm
 + */
 +</code>
 +
 +Utilisation:
 +
 +<code>
 +/**
 + * @swagger
 + *  paths:
 + *    /pet/findByStatus:
 + *      get:
 + *        summary: Finds pets by Status
 + *        tags:
 + *          - pets
 + *        ...
 + *    /pet:
 + *      post:
 + *        summary: Adds a new pet to the store
 + *        tags:
 + *          - pets
 + *        ...
 + *    /store/inventory:
 + *      get:
 + *        summary: Returns pet inventories
 + *        tags:
 + *          - store
 + *        ...
 + */
 +</code>
 +
 +
 +====== 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]]
  
web/javascript/nodejs/swagger.1610055479.txt.gz · Dernière modification : 2022/02/02 00:43 (modification externe)