search

dapr / sig-api

Repository for Dapr API Special Interest Group
Apache License 2.0
18 stars 5 forks source link

Re-start SIG API Component Standardization (HTTP 1.0) #7

Closed salaboy closed 11 months ago

salaboy commented 1 year ago

Folks, I am creating this PR to propose an Open API Schema per Dapr Component, starting with Statestore and PubSub. Besides the OpenAPI Schemas I firmly believe that we need to have a Technology Compatibility Kit (tck) to make sure that these definitions are working against the existing implementation (daprd).

This PR includes:

I wanted to create a proposal for a workflow on how we can get this done iteratively and make sure that we have the right pieces in place to make steady progress.

Please review and merge if possible so I can continue covering paths.

salaboy commented 1 year ago

I did some experiments with generating OpenAPI from dapr .proto files to Open API generate schemas: https://github.com/dapr/sig-api/pull/7/files#diff-05b43e3ee5de1f2f78967f9e8ed4a43619f693e33880ec0cc1899aee489a4644 but unless I am missing something we cannot automatically generate the paths for the statestore endpoints from those .proto definitions.

Merging the handcrafted OpenAPI schema with the paths with the schemas generated by the .proto sounds complicated at this point, but it might be an avenue to investigate further.

salaboy commented 12 months ago

Team, after some work, I've cleaned up this PR only to include the initial bits for the Open API specs for Statestore and PubSub. The idea of this PR is to get the mechanisms in place to keep adding one by one the endpoints (paths) to cover all the Statestore and Pubsub APIs. This PR also includes a GitHub Action that validates the spec against daprd using Docker Compose, Portman, Postman, and Newman. So every time we change the spec, it will run some contract, content, and variation tests against daprd to ensure the API reflects the implementation.

I would appreciate feedback on this, as for me to move forward, the basic bits need to be merged.

salaboy commented 12 months ago

@artursouza @yaron2 can you please review this?