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

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

houqp commented on a change in pull request #10417:
URL: https://github.com/apache/airflow/pull/10417#discussion_r475180202



##########
File path: airflow/api_connexion/openapi/v1.yaml
##########
@@ -1076,7 +1111,7 @@ paths:
 
   /version:
     get:
-      summary: Get version information
+      summary: Get a version information

Review comment:
       would be better to just say `Get current Airflow version` here. It's unclear what `version information` actually means.
   
   in the response section below, we have the description set to `Return current configuration`. Is this still accurate?

##########
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:
       I feel like we can just use `Get the health status of Airflow's metadatabase and scheduler` as summary here and remove the description key. `Get an instance status` doesn't really mean anything from an external reader's point of view.




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