4 ms·

Well let's turn the statement around then: can you create a OpenAPI YAML by hand then? At least with XML and XSD you have proper auto complete. I really no nee

Well let's turn the statement around then: can you create a OpenAPI YAML by hand then? At least with XML and XSD you have proper auto complete. I really no need see the need to use a schema for JSON. The only thing it has going for it compared to SOAP/XML is the fact the it faster parsing and that it has no schema.

paulddraper 5y ago
I can certainly create a JSONSchema (the XSD equivalent) by from memory (except for the $schema URI): { "type": "object", "properties": { "foo": { "type": "string" } } } And at least in VSCode, I get autocomplete too. OpenAPI...I personally don't use this as much but yes there are hundred tutorials on creating definitions by hand.
IggleSniggle 5y ago
You can get proper autocomplete out of OpenAPI, powered by typescript.
dolmen 5y ago
> can you create a OpenAPI YAML by hand then? Of course. > At least with XML and XSD you have proper auto complete. Tooling for OpenAPI exist. In VS Code for example. > I really no need see the need to use a schema for JSON Don't you see the need for precise machine readable description of JSON input and output for a REST API for validation? This is OpenAPI..
pionar 5y ago
Yes, you can. Since OpenAPI itself has a JSON schema, you can get autocomplete from any editor that supports JSON schema. At my company, we found that the auto-OAS generation tools were too brittle and didn't communicate enough information, so we actually do write our own OAS and run automation to make sure it's accurate. That's also how our architects communicate with developers about an endpoint - create an OAS for it.
- stueynz 5y ago
  > At my company, we found that the auto-OAS generation tools were too brittle and didn't communicate enough information, so we actually do write our own OAS and run automation to make sure it's accurate. I found all OAS spec authoring tooling to be useless toys when building non-trivial real world specs. The depths of depravity I’m forced to is as follows: 1. Data model in SparxEA because it’s the tool we have in the depths of govt. Generate XSD from tool 2. XSLT to turn the XSD into matching JSON Schema because I’m old and can still remember how. 3. Hand write the OAS with $ref into JSON schema as appropriate 4. Curate sample payloads to be educationally useful 5. Generate CURL and various code samples 6. Bundle it all into approx 80k lines of machine written wondrousness - 7. ReDoc and Mkdocs to build static website with more documentation All the work is at data modeling, OAS sample curation and mkdocs documentation Things I wish JSON and Schema had: 1. An equivalent of xs:decimal that JS would use number & double are just plain useless in real world commerce with dollars & cents and bulk item pricing with 3&4 decimal places 2. Has taken the time to fix rfc3399 and give Dates a Timezone suffix. Too many languages Marshall a date into datetime. How many bugs have I seen where it’s broken in the morning and works in the afternoon because the damn server is running in AU with UTC Timezone and we’re in NZ

paulddraper 5y ago

I can certainly create a JSONSchema (the XSD equivalent) by from memory (except for the $schema URI): { "type": "object", "properties": { "foo": { "type": "string" } } } And at least in VSCode, I get autocomplete too. OpenAPI...I personally don't use this as much but yes there are hundred tutorials on creating definitions by hand.

IggleSniggle 5y ago

You can get proper autocomplete out of OpenAPI, powered by typescript.

dolmen 5y ago

> can you create a OpenAPI YAML by hand then? Of course. > At least with XML and XSD you have proper auto complete. Tooling for OpenAPI exist. In VS Code for example. > I really no need see the need to use a schema for JSON Don't you see the need for precise machine readable description of JSON input and output for a REST API for validation? This is OpenAPI..

pionar 5y ago

Yes, you can. Since OpenAPI itself has a JSON schema, you can get autocomplete from any editor that supports JSON schema. At my company, we found that the auto-OAS generation tools were too brittle and didn't communicate enough information, so we actually do write our own OAS and run automation to make sure it's accurate. That's also how our architects communicate with developers about an endpoint - create an OAS for it.

stueynz 5y ago
> At my company, we found that the auto-OAS generation tools were too brittle and didn't communicate enough information, so we actually do write our own OAS and run automation to make sure it's accurate. I found all OAS spec authoring tooling to be useless toys when building non-trivial real world specs. The depths of depravity I’m forced to is as follows: 1. Data model in SparxEA because it’s the tool we have in the depths of govt. Generate XSD from tool 2. XSLT to turn the XSD into matching JSON Schema because I’m old and can still remember how. 3. Hand write the OAS with $ref into JSON schema as appropriate 4. Curate sample payloads to be educationally useful 5. Generate CURL and various code samples 6. Bundle it all into approx 80k lines of machine written wondrousness - 7. ReDoc and Mkdocs to build static website with more documentation All the work is at data modeling, OAS sample curation and mkdocs documentation Things I wish JSON and Schema had: 1. An equivalent of xs:decimal that JS would use number & double are just plain useless in real world commerce with dollars & cents and bulk item pricing with 3&4 decimal places 2. Has taken the time to fix rfc3399 and give Dates a Timezone suffix. Too many languages Marshall a date into datetime. How many bugs have I seen where it’s broken in the morning and works in the afternoon because the damn server is running in AU with UTC Timezone and we’re in NZ