Ask a Question

Adding multiple descriptive text for tags / summary:

benpo
New Contributor

Adding multiple descriptive text for tags / summary:

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?
4 REPLIES 4
ponelat
Staff

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
New Contributor

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
Staff

@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?

 

ponelat_0-1672405067009.png

1. Tag 

2. Tag Description

3. Operation (Method + Summary or Description)

4. External docs for Tag 

benpo
New Contributor

I am rendering in Redoc.

cancel
Showing results forΒ 
Search instead forΒ 
Did you mean:Β