speakeasy-api / cli Goto Github PK

Switch brew tap back to api - currently it is brew install speakeasy-api/homebrew-taps/cli which results in the command line tool executable being named cli

Acceptance Criteria:

• Executing brew install speakeasy-api/homebrew-taps/cli results in executable on home path with api alias.

Priority for post-parsing fix: How do we show if a sub-object of a request object is required? We only have annotations for the top object.
say we have:
// @Param type body input.MerchantStatement true "Request schema"

where the input.MerchantStatement object is required, and MerchantStatement looks like:

type MerchantStatement struct {
   Type     models.StatementType `json:"type"`
   FileType *StatementFileType    `json:"file_type,omitempty"`
}

How in API specs, do we intent to be able to mark sub fields of an object with mandatory or not (say Type was mandatory but FileType was not)? Will Speakeasy look at the json tags or object type?

Bolt often uses aliases for package imports.

Example: import api_views "hail/services/api/views" instead of import hail/services/api/views.

When parsing response / request objects, Speakeasy cannot find the reference for an aliased object ("cannot find type definition: api_views.Model1") but can find if its views.Model1.

We have many "views" subpackages. Renaming all our packages might be a challenge. Do you think it would be possible to look through the objects referenced by their alias name?

Adding in annotations for endpoints only works if the request object is empty. added in an annotation for a new handler with:

// .... 
// @Param merchantStatement body input.MerchantStatement true "Merchant statement to sign"
// ....

where input.MerchantStatement is the input object type.
If this input object is empty then a spec is generated.
If this input has a primitive type like:

type MerchantStatement struct {
   Date     float64              `json:"date"`
}

Then NO SPEC is generated with seg violation (invalid memory address or nil pointer)
if this input has any other references or types in the object like a typed object, it also throws an error.
Adding command line result in thread

Slack: https://speakeasyapi.slack.com/archives/C03BEMS60GZ/p1652809174457429

I tried to add a tag for an endpoint with:

// @title Shopper Accounts Public API
// @Version v1.0
// @description This API documents the different endpoints under Bolt's API Account section.
// @Tag.name Account

but I got an error in the yaml file because of a formatting / indentation problem: I think there is missing 2 indentations for the tag annotation.

68:1 error wrong indentation: expected 2 but found 0 (indentation)

Slack: https://speakeasyapi.slack.com/archives/C03BEMS60GZ/p1652135697230919

Acceptance Criteria:

• Running api init on a service with no annotations results in a default specification that looks like the following:

components: {}
externalDocs: {}
info:
  contact: {}
  description: '@description'
  license:
    name: ""
  title: default
  version: 
openapi: "3.0"
paths: {}

Slack : https://speakeasyapi.slack.com/archives/C03BEMS60GZ/p1651174779421479?thread_ts=1651169437.986739&cid=C03BEMS60GZ

Acceptance Criteria:

• Documentation should be updated such that Annotation of Response types should use {object} instead of {struct}.

Slack: https://speakeasyapi.slack.com/archives/C03BEMS60GZ/p1651184009523929

For Speakeasy, we need to annotate each handler with // @Router /v1/endpoint/path_a [post] . However, we already have this information because each of our routes has a Pattern with the same information

router.Route{
					Name:       "name of handler",
					Method:     http.MethodPost,
					Pattern:    "/v1/endpoint/path_a",
					APIHandler: apiApp.Handler,
},

It would reduce redundant dev work if we didn't need to have the extra annotations in both places

Acceptance Criteria:

• Code parser should recognise the presence of a route grouping and automatically infer path information

Naming a component reference prefix is currently components/object and should be components/schemas/object

If an optional annotation field is left out, can we just **not ** include it in the yaml/json, rather than having it in as empty. For example, we probably will not fill in the license section for open api. Currently this is populated, with an error / warning because if the license attribute is included, then identifier needs to exist.

I don't think this is high priority as it can be deleted but it would be nice to not populate empty fields that we leave blank

slack: https://speakeasyapi.slack.com/archives/C03BEMS60GZ/p1651177994656739

YAML generated: there is a bug in the responses section; no matter what i annotate as the response its name is always E.

Acceptance Criteria:

• Response section includes the complete OpenAPI3.0 Model for Response with no offending characters

Small nit: The speakeasy documentation page has a broken link to github at the top ("View on Github"). The one at the bottom works, though.

whenever running cli init ... we get: output type 'go' not supported

we also are seeing some strange date formats with the output: