Change hsjs-scaffold to include YAML openapi file instead of creating openapi3.ts

[diberry]

Clear and concise description of the problem

Why build a version of the openapi3 as a JSON object when TSP can output the openapi and it can be directly included in the project by relative path as a yaml file?

If the issue is you need to control that the openapi schema is generated even if it hasn't been requested, create the openapi3.yaml file, instead of a .ts file.

From npm package for swagger-ui-express: Load swagger from yaml file.

const express = require('express');
const app = express();
const swaggerUi = require('swagger-ui-express');
const fs = require("fs")
const YAML = require('yaml')

const file  = fs.readFileSync('./swagger.yaml', 'utf8')
const swaggerDocument = YAML.parse(file)

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));

@willmtemple @mario-guerra

Checklist

• Follow our Code of Conduct
• Read the docs.
• Check that there isn't already an issue that request the same feature to avoid creating a duplicate.

[witemple-msft]

@diberry The reason HSJS handles the OpenAPI3 document generation this way is so that the copy of the document that the Swagger UI loads is always exactly representative of what the server was generated from. If you edit the typespec and recompile the OpenAPI3 document, but not the HSJS server, the two can get out of sync. With this method, where openapi3.ts is generated with the document inside it, the server implementation is never out of sync with the swagger UI because the two are part of the same generation. This also means the generated server doesn't have to take a hard dependency on a YAML parser; it can just load the document as a JS module and pass it to the plugin.

We definitely could do this the other way but it requires us to parse the openapi3 emitter's options to figure out where the output YAML is written relative to the server and interpret its default settings, and the document probably won't be in the same directory as the rest of the generated server, so if there's no problem or issue with outputting the generated openapi3.ts document I'd prefer to keep it that way since I can very easily just get the document and write it to that file while I'm emitting the rest of the server.

[markcowl]

Per discussion, closing as won't fix