Swagger Document Requirements 4 6 2014

I am connecting to https://raw.github.com/openphacts/OPS_LinkedDataApi/1.3.0/api-config-files/swagger.json

• I guess this is still the recent version? Generally, very most things are already in place. Thanks for this! So I hope the missing things will not take too much time? The response template is currently contained as HTML in the general description. This should at least be transfered into a separate swagger node. Moreover, it is not easy to visually interprete the response structure/hierarchy from it and it seems to be not easily machine-interpretable. To change this may take some more time. So I would set it a B priority since for the time being, a proper extraction of the response hierarchy might be achieved by other means. Sometimes, important information is only available as free text. Example: Option "_PageSize" in /compound/members/pages. Description: "Set to all to retrieve all results in a single page". As _PageSize is an integer, this info should be available in an additional swagger node because automatic approaches may fail otherwise here. _orderBy: Generally ok. The question is if it would be easier to split the allowableValues from the sort direction (ASC()/DESC()). Again, important information for interpretation of this option is free text only: "Multiple values can be specified separated as spaces". The question is, if for valueType LIST we need a distinction between single-select and multi-select lists as a separate information in swagger? My prio AAA: Allowable values available as free text description only. Example: /compound/classificationForTargets, option "tree" or "activity_relation". Description: "Currently one of 'chembl', 'enzyme', 'go' or ">,>=,=,<,<=". It is clear that this belongs into an allowableValues node (in these cases with a single-select limitation). References to other calls in free-text descriptions. Example: /compound/classificationForTargets, option "activity type", "activity_unit" etc. I believe they should have an own swagger node. Reason: One might follow these references during an automatic component creation step and create an allowableValues list from it. I would give it an A prio therefore.