Adding multiple descriptive text for tags / summary:

[benpo]

Hi, I am a newbie, so probably asking a stupid question. 

I am editing a YAML file that looks like this:

paths:

  /api/login:

    post:

      summary: User login

      tags:

        - Authentication

      description: Use the credentials to log in.

      requestBody:

        description: Login credentials<br/>

        required: true

        content:

          application/json:

            schema:

              type: object

              required:

                - username

                - password

              properties:

                username:

                  type: string

This displays something like this:

Authentication

User login

Use the credentials to log in.

 I want to add some text underneath Authentication, which describes the entire authentication process etc. (as well as keep the text already present underneath User Login for additional information)  -  I cannot work out how to do it? - Can anyone help a newbie?

[ponelat]

Hey @benpo 

Not a silly question 🙂

I think the best avenue is to make use of Tag Descriptions, here are some docs around it https://swagger.io/docs/specification/2-0/grouping-operations-with-tags/

Here is an example: https://app.swaggerhub.com/apis/SwaggerPMTests/tag-with-description/1.0.0#/Authentication

[benpo]

Thanks @ponelat .

Do I understand from the documentation that what I want to achieve is not possible?

I want to put a description text under the Authentication tag heading. There is already description text there, which is displayed in the  User Login section (which I also want) Ideally i would like to have an output like this:

Authentication

Some text about Authentication.

User login

Use the credentials to log in. 

[ponelat]

@benpo I don't know what is generating that rendering, is it SwaggerUI or some other tool? 

Did you look into the SwaggerHub example above?

1. Tag 

2. Tag Description

3. Operation (Method + Summary or Description)

4. External docs for Tag 

[benpo]

I am rendering in Redoc.