[GitHub] [airflow] mik-laj commented on a change in pull request #10417: Improving descriptions in OpenAPI

[GitBox <gi...@apache.org>]

mik-laj commented on a change in pull request #10417:
URL: https://github.com/apache/airflow/pull/10417#discussion_r475181157



##########
File path: airflow/api_connexion/openapi/v1.yaml
##########
@@ -1052,17 +1064,40 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/Config'
+              example:
+                sections:
+                  - name: core
+                    options:
+                      - key: dags_folder
+                        value: /home/user/my-dags-folder
+
+                  - name: smtp
+                    options:
+                      - key: smtp_host
+                        value: localhost
+                      - key: smtp_mail_from
+                        value: airflow@example.com
             text/plain:
               schema:
                 type: string
+              example: |
+                [core]
+                dags_folder = /home/user/my-dags-folder
+                [smtp]
+                smtp_host = localhost
+                smtp_mail_from =  airflow@example.com
+
+
         '401':
           $ref: '#/components/responses/Unauthenticated'
         '403':
           $ref: '#/components/responses/PermissionDenied'
 
   /health:
     get:
-      summary: Returns the status of Airflow's metadatabase and scheduler
+      summary: Get a instance status
+      description: |
+        Get the status of Airflow's metadatabase and scheduler.

Review comment:
       The summary should be no longer than 20 characters to make it accessible to all people. The description can be of any length. I don't think the problem is that the summary doesn't say everything as users can access the full description easily, but the short titles make it easier to navigate.
   
   <img width="300" alt="Screenshot 2020-08-23 at 08 56 27" src="https://user-images.githubusercontent.com/12058428/90973025-8ddbe700-e51e-11ea-8947-b34bfcc4b82e.png">
   https://airflow.readthedocs.io/en/latest/stable-rest-api-ref.html#tag/Monitoring
   




----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org