search

serverless / typescript

TypeScript definitions for Serverless Framework service configuration
141 stars 25 forks source link

Request: Improve documentation to explain where the JSON schema files used to generate the TS definitions come from #57

Open Woodz opened 2 years ago

Woodz commented 2 years ago

I'm very excited to see the automation involved in this repository to ensure the definitions are kept up to date. However, tracing the origin of the definitions is quite hard because the documentation just states

It aims to automate service file TypeScript definitions based on JSON-schema used by serverless/serverless for validation at the beginning of any Serverless CLI command

However, trying to find which JSON schemas this repo uses is very hard, since there is no mention of where these schemas are on:

With some digging, I found https://github.com/serverless/serverless/blob/739045d9bb03ddefcacceca0bd39f188517b187d/lib/plugins/aws/provider/awsProvider.js#L235 but this doesn't seem to match the TS definitions, so it is probably not the right one.

Specifically, I am trying to find what the purpose of the outputs object at the root level is (not to be confused with the expected resources.Outputs object), but cannot answer this question easily.

I'd appreciate any clarification on the JSON schemas used, thanks!

fredericbarthelet commented 2 years ago

Hi @Woodz, thanks for opening this issue. JSON schema used by the Serverless framework to validate any service file is programmatically built using a set of APIs, mostly exposed to plugin developers, in order to allow them to expand framework capabilities with new properties. This API is also used internally by framework core features, as each of them is actually develop in the form of a plugin.

The API is documented in https://www.serverless.com/framework/docs/guides/plugins/custom-configuration#validating-the-configuration and you can indeed find part of the final schema defined internally in the framework:

I'd welcome a PR explaining this in the README of this repository if you feel like doing one :)

As far as outputs object is concerned, you can find the related documentation in https://www.serverless.com/framework/docs/guides/output-variables

kopertop commented 1 year ago

@fredericbarthelet could you explain HOW the deployment of a new release is handled? Just running npm run build does not update the index.d.ts file, and even adding sls deploy afterwards doesn't touch it. In the event this build is NOT automated, is there a way we can run it to get the latest typings?