[GitHub] [airflow] SamWheating opened a new pull request, #30149: Use allOf in OpenAPI Spec to remove state field from trigger Dagrun API docs

[via GitHub]

SamWheating opened a new pull request, #30149:
URL: https://github.com/apache/airflow/pull/30149

   Closes: https://github.com/apache/airflow/issues/30075
   
   **Note:** We should either merge this _or_ 
https://github.com/apache/airflow/pull/30113, but not both.
   
   Using `$ref` alongside other attributes can lead to unintentional errors in 
the API documentation 
([source](https://swagger.io/docs/specification/using-ref/)):
   
   > Any sibling elements of a $ref are ignored. This is because $ref works by 
replacing itself and everything on its level with the definition it is pointing 
at.
   
   Because of this, the `state` field was incorrectly showing up in the API 
docs for the trigger DagRun endpoint:
   
   <img width="1311" alt="Screenshot 2023-03-16 at 9 36 37 AM" 
src="https://user-images.githubusercontent.com/16950874/225691402-08baa350-177a-4836-a3b5-2cada94bf6da.png";>
   
   By instead these attributes under `allOf:`, this change removes this field 
from the docs, making it more consistent with the intended API behaviour:
   <img width="1327" alt="Screenshot 2023-03-16 at 9 38 03 AM" 
src="https://user-images.githubusercontent.com/16950874/225691638-364e64fd-e030-403c-8111-c40b5b721691.png";>
   
   There are a few other instances in the Spec in which $ref is used alongside 
another attribute which could lead to similar issues, I will fix those in a 
subsequent PR when I have a bit more time.
   


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

To unsubscribe, e-mail: commits-unsubscr...@airflow.apache.org

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