Re: Working Group Visibility and Spec Documentation

Hey all,

Just wanted to give an update on my research on using OpenAPI for the normative text:

It seems that with OpenAPI we can have define normative text in a form of:
Any arbitrary tool that supports OpenAPI, e.g. ReDoc (https://redocly.github.io/redoc/ <https://redocly.github.io/redoc/>) - see example of WebDriver: https://webdriver.github.io/webdriver/ <https://webdriver.github.io/webdriver/>
As a yaml or json file (with or without normative text)
In a ReSpec format (should not take that much to build a compiler that moves the yaml information into a ReSpec format)

Next to being able for machine to consume the format, it seems to be much easier to maintain because we wouldn’t have to write HTML code and instead have everything nicely ordered in files. Check out my current working draft: https://github.com/webdriver/webdriver/tree/master/openapi <https://github.com/webdriver/webdriver/tree/master/openapi>

Any feedback is appreciated!

Cheers
Christian

> On Sep 25, 2019, at 12:21 PM, Christian Bromann <christian.bromann@saucelabs.com> wrote:
> 
> Hey James,
> 
> Thanks for your feedback, let me address some of your concerns:
> 
>> the status of swagger is unclear to me
> 
> After doing some research it seems that the swagger project was donated to the OpenAPI initiative (https://www.openapis.org/ <https://www.openapis.org/>) which has an open governance structure under the Linux Foundation. The swagger specification was also renamed to OpenAPI (https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md <https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md>).
> 
>> In addition any non-normative material needs to be clearly marked as such and there needs to be a clear commitment to keeping it up to date with the spec.
> 
> I see the webdriver OpenAPI specification (https://app.swaggerhub.com/apis-docs/christian-bromann/webdriver/2.0.0 <https://app.swaggerhub.com/apis-docs/christian-bromann/webdriver/2.0.0>) more as a documentation artifact to the spec without being normative at all. It should help framework developers to understand the API interface better and is not directed to implementers like browser vendors et. al. For example, me, as maintainer of WebdriverIO will use this document, to autogenerate my bindings (https://www.npmjs.com/package/webdriver <https://www.npmjs.com/package/webdriver>), include type checks and documentation for the WebdriverIO website. 
> 
>> I would much prefer an approach where we actually replace spec prose with e.g. JSON Schema in the normative requirements. Once that happens it will be easier to build tools to generate non-normative descriptions from the spec itself and solve the update problem.
> 
> That sounds like a great idea. In fact it would allow use to split up the specification in multiple files and reference all parts in a main document (https://swagger.io/docs/specification/using-ref/ <https://swagger.io/docs/specification/using-ref/>). At the end the specification as HTML document can be generated by the OpenAPI definition. I am happy to explore this path if others feel this to be a good idea too.
> 
> That said, my goal is, separate from the WebDriver specification, to improve the visibility and discoverability of our working group doings by creating a website similar to what other working groups already do (e.g. Service Worker WG).
> 
> More feedback is appreciated!
> 
> Cheers
> Christian
> 
>> On Sep 24, 2019, at 2:35 PM, James Graham <james@hoppipolla.co.uk <mailto:james@hoppipolla.co.uk>> wrote:
>> 
>> 
>> 
>> On 24/09/2019 12:42, Christian Bromann wrote:
>> 
>>>  * have a swagger editor (like https://editor.swagger.io/ <https://editor.swagger.io/>) with all
>>>    WebDriver endpoints for easier discoverability
>>>      o I already ported our spec into such swagger definition:
>>>        https://app.swaggerhub.com/apis-docs/christian-bromann/webdriver/2.0.0 <https://app.swaggerhub.com/apis-docs/christian-bromann/webdriver/2.0.0>
>> 
>> I'm not opposed to making parts of the spec more machine readable — indeed I would advocate for it — but I'm somewhat concerned about publishing this kind of thing as an adjunct to the spec. For a start, the status of swagger is unclear to me; it claims to have a specification but it's very very thin, and attempts to monkey patch JSON schema (which has a much more detailed spec) to describe schema for HTTP bodies. In addition any non-normative material needs to be clearly marked as such and there needs to be a clear commitment to keeping it up to date with the spec. Otherwise there is a problem whenever the normative requirements and non-normative descriptions don't match (for example: that swagger definition doesn't match the spec for New Session, which is one of the first endpoints I looked at).
>> 
>> I would much prefer an approach where we actually replace spec prose with e.g. JSON Schema in the normative requirements. Once that happens it will be easier to build tools to generate non-normative descriptions from the spec itself and solve the update problem.
>> 
>