fern-api / fern Goto Github PK
View Code? Open in Web Editor NEWInput OpenAPI. Output SDKs and Docs.
Home Page: https://buildwithfern.com
License: MIT License
Input OpenAPI. Output SDKs and Docs.
Home Page: https://buildwithfern.com
License: MIT License
Allows an easy way to handle pre-existing JSON
Add an example spec to the Fern repo. It should include Rest + Websockets.
The IR should generate unique names for HTTP requests & responses (WireMessage should be a TypeDefiniton instead of a Type)
It doesn't make sense to extend union
, enum
, or an alias
because it is unclear what the extended type would look like (i.e. why would I ever extend a union instead of adding it as a field).
We should validate that only objects
are allowed to be extended.
DayOfWeekService:
auth: none
endpoints:
getCurrentDayOfWeek:
method: GET
path: /day-of-week
response: DayOfWeek
Our opinion is that many devs will don't actually care about the method
or path
of the endpoint as long as they can declare inputs and outputs.
Fern should support devs not specifying method
or path
. It can default method
to POST
and path
to the endpoint id. This provides the flexibility to integrate existing APIs while allowing devs to iterate faster on their APIs by reducing config required.
@dannysheridan encountered a case where a set of endpoints take the same 10 query-params. It's annoying to copy paste them everywhere and changing one things requires you to make edits in n different places.
Should we have a concept of grouped query params?
It should be really easy for the FE to subscribe to "topics", and easy for the backend to send those updates to each FE
Enums should have a name
and value
field. If the enums are alphanumeric then value defaults to name, but if not then name
needs to be specified so that codegen can be done properly.
created_at_utc: "1981-11-30T10:44:38.567Z"
I want to know:
Other:
Once we have strongly-typed plugin config, we can make the type of output a "filepath" so we know to map it on the container
Blocked on prettier/prettier#12763
But first make sure it's actually faster
The generated SDK should make it very easy to 1/ iterate over all pages, 2/ ask simple questions like .is_next_page_available()
. In order to do this the Fern Definition must understand what the pagination scheme is.
It would be cool if fern visualize
would fire up a local ui where you can edit and changes are written back to your yaml files.
No code UI at the edge
@zachkirsch i think every wire message should have an id that makes it very easy to trace through your api while debugging. The IDs have been invaluable in my experience and fern is in a great position to bake them in.
Can see us building a self-hostable analytics tool on top that can track those IDs and make it very easy for PMs + Devs to understand metrics/filter.
to make it extra clear what that package is
The rules for the wire format are a little tricky (depending on if the unioned type is an object or not). Better to encode this in the IR than to do it correctly in each plugin.
We can often find the sourceFile from declaration.getSourceFile()
fern generate --name would run that generator. The problem is that you can have the same generator multiple times so how do you differentiate across those?
@zachkirsch what do you think about having filepath in service as well?
Take a look at the run codegen
stage in this CircleCI workflow: https://app.circleci.com/pipelines/github/fern-api/fern/415/workflows/e78eefec-5405-405e-a961-e7b7db9add7d/jobs/873. We need to provide a --event-based output option that only logs changes (cdk does something similar).
Example of API using them
Rather than just a top-level errors/model/services
So we can default to it! instead of making the client enter it manually
tip?: double instead of tip: optional< double >
Easier readability, follows typescript convention
I think the yaml is cleaner when it reads like
storeTracedWorkspaceV2:
http: POST /store-workspace-trace-v2/submission/{submissionId}
path-parameters:
submissionId: submission.SubmissionId
query-parameters:
stuff: Stuff
body: list<submission.TraceResponseV2>
as opposed to
storeTracedWorkspaceV2:
http: POST /store-workspace-trace-v2/submission/{submissionId}
parameters:
submissionId: submission.SubmissionId
query-parameters:
stuff: Stuff
body: list<submission.TraceResponseV2>
Rules for a linter to evaluate given the input of fern.yml
A command-line command of fern validate
that takes my YML and checks for mistakes/errors before I run fern generate
What are the best practices about where to put objects relative to each other?
How ought a dev organize their objects as they relate to their services? I think the first object mentioned in Services should be the first listed in Objects. The second object mentioned in Services should be the second in Objects, and so on.
Could we encode the best practices in a linter or validation?
Support binary as a first class primitive in the spec.
joinPaths takes null strings but I don't think we need it
It lets you add dependsOn!
This is platform dependent re the file system, and thus isn't good for URLs. Same with postman plugin!
If docker daemon is running we should have a validation error and point users to https://docs.docker.com/get-docker/ (really the specific link based on their OS)
Then add to the Readme example.
e.g. queryParameters
vs auth-override
i.e. string matches regex, int is positive, string is an ISO 8601 date
In #130, we switched to depending on @zachkirsch/prettier
since there's a bug in prettier re dynamic requires with webpack. The fix is in prettier/prettier#12797, once that merges + releases, we should switch back.
Creating issue where we can jot down all validations we have to add:
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.