speakeasy-api / cli Goto Github PK
View Code? Open in Web Editor NEWTrack the state of your API and orchestrate your API lifecycle from code to artifacts to infra. Manage your APIs with ease !
License: Apache License 2.0
Track the state of your API and orchestrate your API lifecycle from code to artifacts to infra. Manage your APIs with ease !
License: Apache License 2.0
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
Slack: https://speakeasyapi.slack.com/archives/C03BEMS60GZ/p1652135697230919
Acceptance Criteria:
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/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:
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
with no offending charactersSmall nit: The speakeasy documentation page has a broken link to github at the top ("View on Github"). The one at the bottom works, though.
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?
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
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?
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:
brew install speakeasy-api/homebrew-taps/cli
results in executable on home path with api
alias.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)
Naming a component reference prefix is currently components/object
and should be components/schemas/object
Acceptance Criteria:
{object}
instead of {struct}
.A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.