web-dev-qa-db-fra.com

Comment formater les descriptions de texte Swagger 2.0?

J'aimerais formater mes descriptions d'API Swagger afin qu'elles ne soient pas de simples paragraphes de texte. De préférence, j'aimerais y ajouter une petite table.

Je n'ai pas trouvé de référence en ligne sur le formatage du texte dans les descriptions Swagger. Si je lance le Swagger Editor et que j'ouvre l'exemple Instagram (File\Open Example\Instagram.yaml), la première description du fichier yaml montre une mise en forme, notamment un lien hypertexte et un cadre de sélection:

    [registered your client](http://instagram.com/developer/register/) it's easy
to start requesting data from Instagram.

```
  https://api.instagram.com/v1/media/popular?client_id=CLIENT-ID
```

Cela ressemble à la norme Markdown , mais lorsque j'ajoute une réduction de table à la description des exemples, l'éditeur affiche une erreur:

|Col1|Col2|
|------|------|
|1|2|


YAML Syntax Error
End of the stream or a document separator is expected at line 36, column

Quelle est la mise en forme permise par Swagger 2.0? Est-ce que je fais quelque chose de mal pour rendre une table?

restmarkdownswaggerswagger-2.0swagger-editor
28
TERACytE

Markdown est pris en charge dans Swagger Editor. Voici un exemple d'utilisation de Markdown dans un document OpenAPI (Swagger):

swagger: '2.0'
info:
  version: 0.0.0
  title: Markdown 
  description: |
    # Heading

    Text attributes _italic_, *italic*, __bold__, **bold**, `monospace`.

    Horizontal rule:

    ---

    Bullet list:

      * apples
      * oranges
      * pears

    Numbered list:

      1. apples
      2. oranges
      3. pears

    A [link](http://example.com).

    An image:
    ![Swagger logo](https://raw.githubusercontent.com/swagger-api/swagger-ui/master/dist/favicon-32x32.png)

    Code block:

    ```
    {
      "message": "Hello, world!"
    }
    ```

    Tables:

    | Column1 | Collumn2 |
    | ------- | -------- |
    | cell1   | cell2    |
paths:
  /:
    get:
      responses:
        200:
          description: OK

Vous pouvez copier et coller l’exemple ci-dessus dans Swagger Editor pour afficher le résultat.

69
Wilson