Semantic error at the path (e.g. "paths./v2/link/provider/oauth/{oauth_provider}.get.requestBody") GET operations cannot have a requestBody.

• workspaces should be aliased in fern.config.json I could see fern.config.json changing to

{
  "workspaces": {
     "coordinator-api": "/path/to/coordinator"
  }
}

We can get rid of the "auto find all your .fernrcs" which also creates problems for us in this repo when we add a ton of nested fern api workspaces for testing.

• fern init asks you for an api name and will add to the fern.config.json and initialize a new workspace

• fern generate asks you what workspace you want to generate for if you forget to specify!

Either use placeholders (e.g. when a request requires a name, make it name: DEFAULTRESPONSENAMECHANGEME or have the CLI prompt the user for the parameter value)

Summary

This PR enables the updated documentation setup for Fern, to be available at buildwithfern.com/docs and currently for preview at fern.mintlify.app

🚀 Setup

Simply merge in this PR and your documentation will be connected!

👩‍💻 Development

Install the Mintlify CLI to preview the documentation changes locally. To install, use the following command

npm i mintlify -g

Run the following command at the root of your documentation (where mint.json is)

mintlify dev

😎 Publishing Changes

Changes will be deployed to production automatically after pushing to the default branch.

You can also preview changes using PRs, which generates a preview link of the docs.

Troubleshooting

• Mintlify dev isn't running - Run mintlify install it'll re-install dependencies.
• Mintlify dev is updating really slowly - Run mintlify clear to clear the cache.

dsheridan@air-diesel fern-climatiq % fern generate
fern generate [workspaces...]

Generate typesafe servers and clients

Positionals:
  workspaces  If omitted, every workspace specified in the project-level configu
              ration (fern.config.json) will be processed. [array] [default: []]

Options:
      --help        Show help                                          [boolean]
      --keepDocker  If true, Docker containers are not removed after generation.
                     This is ignored for remote generation.
                                                      [boolean] [default: false]
      --local       If true, code is generated using Docker on this machine.
                                                      [boolean] [default: false]
  -v, --version     Show version number                                [boolean]

[AxiosError: Request failed with status code 500] {
  code: 'ERR_BAD_RESPONSE',
  config: {
    transitional: {
      silentJSONParsing: true,
      forcedJSONParsing: true,
      clarifyTimeoutError: false
    },
    adapter: [Function: httpAdapter],
    transformRequest: [ [Function: transformRequest] ],
    transformResponse: [ [Function: transformResponse] ],
    timeout: 0,
    xsrfCookieName: 'XSRF-TOKEN',
    xsrfHeaderName: 'X-XSRF-TOKEN',
    maxContentLength: -1,
    maxBodyLength: -1,
    env: { FormData: [Function] },
    validateStatus: [Function: validateStatus],
    headers: {
      Accept: 'application/json, text/plain, */*',
      'Content-Type': 'multipart/form-data; boundary=--------------------------350140785974621542563728',
      'User-Agent': 'axios/0.27.2',
      'content-type': 'multipart/form-data; boundary=--------------------------350140785974621542563728'
    },
    method: 'post',
    url: 'https://fiddle-coordinator.buildwithfern.com/api/remote-gen/jobs/31fa1f35-46c8-4339-aed1-67a37ed97254/start',
    data: FormData3 {
      _overheadLength: 103,
      _valueLength: 33613,
      _valuesToMeasure: [],
      writable: false,
      readable: true,
      dataSize: 0,
      maxDataSize: 2097152,
      pauseStreams: true,
      _released: true,
      _streams: [],
      _currentStream: null,
      _insideLoop: false,
      _pendingNext: false,
      _boundary: '--------------------------350140785974621542563728',
      _events: [Object: null prototype],
      _eventsCount: 1
    }
  },
  request: <ref *1> ClientRequest {
    _events: [Object: null prototype] {
      abort: [Function (anonymous)],
      aborted: [Function (anonymous)],
      connect: [Function (anonymous)],
      error: [Function (anonymous)],
      socket: [Function (anonymous)],
      timeout: [Function (anonymous)],
      prefinish: [Function: requestOnPrefinish]
    },
    _eventsCount: 7,
    _maxListeners: undefined,
    outputData: [],
    outputSize: 0,
    writable: true,
    destroyed: false,
    _last: true,
    chunkedEncoding: true,
    shouldKeepAlive: false,
    maxRequestsOnConnectionReached: false,
    _defaultKeepAlive: true,
    useChunkedEncodingByDefault: true,
    sendDate: false,
    _removedConnection: false,
    _removedContLen: false,
    _removedTE: false,
    _contentLength: null,
    _hasBody: true,
    _trailer: '',
    finished: true,
    _headerSent: true,
    _closed: false,
    socket: TLSSocket {
      _tlsOptions: [Object],
      _secureEstablished: true,
      _securePending: false,
      _newSessionPending: false,
      _controlReleased: true,
      secureConnecting: false,
      _SNICallback: null,
      servername: 'fiddle-coordinator.buildwithfern.com',
      alpnProtocol: false,
      authorized: true,
      authorizationError: null,
      encrypted: true,
      _events: [Object: null prototype],
      _eventsCount: 10,
      connecting: false,
      _hadError: false,
      _parent: null,
      _host: 'fiddle-coordinator.buildwithfern.com',
      _readableState: [ReadableState],
      _maxListeners: undefined,
      _writableState: [WritableState],
      allowHalfOpen: false,
      _sockname: null,
      _pendingData: null,
      _pendingEncoding: '',
      server: undefined,
      _server: null,
      ssl: [TLSWrap],
      _requestCert: true,
      _rejectUnauthorized: true,
      parser: null,
      _httpMessage: [Circular *1],
      [Symbol(res)]: [TLSWrap],
      [Symbol(verified)]: true,
      [Symbol(pendingSession)]: null,
      [Symbol(async_id_symbol)]: 190,
      [Symbol(kHandle)]: [TLSWrap],
      [Symbol(lastWriteQueueSize)]: 0,
      [Symbol(timeout)]: null,
      [Symbol(kBuffer)]: null,
      [Symbol(kBufferCb)]: null,
      [Symbol(kBufferGen)]: null,
      [Symbol(kCapture)]: false,
      [Symbol(kSetNoDelay)]: false,
      [Symbol(kSetKeepAlive)]: true,
      [Symbol(kSetKeepAliveInitialDelay)]: 60,
      [Symbol(kBytesRead)]: 0,
      [Symbol(kBytesWritten)]: 0,
      [Symbol(connect-options)]: [Object]
    },
    _header: 'POST /api/remote-gen/jobs/31fa1f35-46c8-4339-aed1-67a37ed97254/start HTTP/1.1\r\n' +
      'Accept: application/json, text/plain, */*\r\n' +
      'content-type: multipart/form-data; boundary=--------------------------350140785974621542563728\r\n' +
      'User-Agent: axios/0.27.2\r\n' +
      'Host: fiddle-coordinator.buildwithfern.com\r\n' +
      'Connection: close\r\n' +
      'Transfer-Encoding: chunked\r\n' +
      '\r\n',
    _keepAliveTimeout: 0,
    _onPendingData: [Function: nop],
    agent: Agent {
      _events: [Object: null prototype],
      _eventsCount: 2,
      _maxListeners: undefined,
      defaultPort: 443,
      protocol: 'https:',
      options: [Object: null prototype],
      requests: [Object: null prototype] {},
      sockets: [Object: null prototype],
      freeSockets: [Object: null prototype] {},
      keepAliveMsecs: 1000,
      keepAlive: false,
      maxSockets: Infinity,
      maxFreeSockets: 256,
      scheduling: 'lifo',
      maxTotalSockets: Infinity,
      totalSocketCount: 1,
      maxCachedSessions: 100,
      _sessionCache: [Object],
      [Symbol(kCapture)]: false
    },
    socketPath: undefined,
    method: 'POST',
    maxHeaderSize: undefined,
    insecureHTTPParser: undefined,
    path: '/api/remote-gen/jobs/31fa1f35-46c8-4339-aed1-67a37ed97254/start',
    _ended: true,
    res: IncomingMessage {
      _readableState: [ReadableState],
      _events: [Object: null prototype],
      _eventsCount: 4,
      _maxListeners: undefined,
      socket: [TLSSocket],
      httpVersionMajor: 1,
      httpVersionMinor: 1,
      httpVersion: '1.1',
      complete: true,
      rawHeaders: [Array],
      rawTrailers: [],
      aborted: false,
      upgrade: false,
      url: '',
      method: null,
      statusCode: 500,
      statusMessage: '',
      client: [TLSSocket],
      _consuming: false,
      _dumped: false,
      req: [Circular *1],
      responseUrl: 'https://fiddle-coordinator.buildwithfern.com/api/remote-gen/jobs/31fa1f35-46c8-4339-aed1-67a37ed97254/start',
      redirects: [],
      [Symbol(kCapture)]: false,
      [Symbol(kHeaders)]: [Object],
      [Symbol(kHeadersCount)]: 14,
      [Symbol(kTrailers)]: null,
      [Symbol(kTrailersCount)]: 0
    },
    aborted: false,
    timeoutCb: null,
    upgradeOrConnect: false,
    parser: null,
    maxHeadersCount: null,
    reusedSocket: false,
    host: 'fiddle-coordinator.buildwithfern.com',
    protocol: 'https:',
    _redirectable: Writable {
      _writableState: [WritableState],
      _events: [Object: null prototype],
      _eventsCount: 3,
      _maxListeners: undefined,
      _options: [Object],
      _ended: true,
      _ending: true,
      _redirectCount: 0,
      _redirects: [],
      _requestBodyLength: 33772,
      _requestBodyBuffers: [],
      _onNativeResponse: [Function (anonymous)],
      _currentRequest: [Circular *1],
      _currentUrl: 'https://fiddle-coordinator.buildwithfern.com/api/remote-gen/jobs/31fa1f35-46c8-4339-aed1-67a37ed97254/start',
      [Symbol(kCapture)]: false
    },
    [Symbol(kCapture)]: false,
    [Symbol(kNeedDrain)]: true,
    [Symbol(corked)]: 0,
    [Symbol(kOutHeaders)]: [Object: null prototype] {
      accept: [Array],
      'content-type': [Array],
      'user-agent': [Array],
      host: [Array]
    }
  },
  response: {
    status: 500,
    statusText: '',
    headers: {
      date: 'Tue, 02 Aug 2022 16:26:03 GMT',
      'content-type': 'application/json',
      'content-length': '79',
      connection: 'close',
      'access-control-allow-origin': '*',
      'access-control-allow-headers': '*',
      'access-control-allow-methods': 'OPTIONS,GET,PUT,POST,DELETE,HEAD'
    },
    config: {
      transitional: [Object],
      adapter: [Function: httpAdapter],
      transformRequest: [Array],
      transformResponse: [Array],
      timeout: 0,
      xsrfCookieName: 'XSRF-TOKEN',
      xsrfHeaderName: 'X-XSRF-TOKEN',
      maxContentLength: -1,
      maxBodyLength: -1,
      env: [Object],
      validateStatus: [Function: validateStatus],
      headers: [Object],
      method: 'post',
      url: 'https://fiddle-coordinator.buildwithfern.com/api/remote-gen/jobs/31fa1f35-46c8-4339-aed1-67a37ed97254/start',
      data: [FormData3]
    },
    request: <ref *1> ClientRequest {
      _events: [Object: null prototype],
      _eventsCount: 7,
      _maxListeners: undefined,
      outputData: [],
      outputSize: 0,
      writable: true,
      destroyed: false,
      _last: true,
      chunkedEncoding: true,
      shouldKeepAlive: false,
      maxRequestsOnConnectionReached: false,
      _defaultKeepAlive: true,
      useChunkedEncodingByDefault: true,
      sendDate: false,
      _removedConnection: false,
      _removedContLen: false,
      _removedTE: false,
      _contentLength: null,
      _hasBody: true,
      _trailer: '',
      finished: true,
      _headerSent: true,
      _closed: false,
      socket: [TLSSocket],
      _header: 'POST /api/remote-gen/jobs/31fa1f35-46c8-4339-aed1-67a37ed97254/start HTTP/1.1\r\n' +
        'Accept: application/json, text/plain, */*\r\n' +
        'content-type: multipart/form-data; boundary=--------------------------350140785974621542563728\r\n' +
        'User-Agent: axios/0.27.2\r\n' +
        'Host: fiddle-coordinator.buildwithfern.com\r\n' +
        'Connection: close\r\n' +
        'Transfer-Encoding: chunked\r\n' +
        '\r\n',
      _keepAliveTimeout: 0,
      _onPendingData: [Function: nop],
      agent: [Agent],
      socketPath: undefined,
      method: 'POST',
      maxHeaderSize: undefined,
      insecureHTTPParser: undefined,
      path: '/api/remote-gen/jobs/31fa1f35-46c8-4339-aed1-67a37ed97254/start',
      _ended: true,
      res: [IncomingMessage],
      aborted: false,
      timeoutCb: null,
      upgradeOrConnect: false,
      parser: null,
      maxHeadersCount: null,
      reusedSocket: false,
      host: 'fiddle-coordinator.buildwithfern.com',
      protocol: 'https:',
      _redirectable: [Writable],
      [Symbol(kCapture)]: false,
      [Symbol(kNeedDrain)]: true,
      [Symbol(corked)]: 0,
      [Symbol(kOutHeaders)]: [Object: null prototype]
    },
    data: {
      _error: '_unknown',
      _errorInstanceId: '724512fe-d0fc-4ecf-978f-388f4f2cb7fe'
    }
  }
}

https://www.notion.so/usebirch/Fern-Workspace-Terminology-dae519a16ce1421fac15f377c0c82550

repo/
  api/
    .fernrc
    src/
      imdb.yml

1. What do we call the api folder, which contains the Fernrc and the definition?
   1. Workspace
2. What do we call the .fernrc?
   1. Workspace Configuration
3. What do we call the the src/ folder?
   1. API Definition

@zachkirsch i have just hardcoded the url to the next release and we'll have to remember to bump this whenever the json schema changes. The better option i think is to inject a REF constant into the bundle through webpack's DefinePlugin. Ref should either be the commit hash or the tag which we pass to the init command. What do you think of that approach? If good, can take a stab at it.

trying to implement a validation rule to check if imported files actually exist, had to do a couple of interesting things: (1) pass down absoluteDefinitionPath all the way down as RuleRunnerArgs , (2) once i had the absolute path, i could append the imported file path and then check if the file exists but this introduces async into the rules which messes with a lot of the types. curious how you’d approach this instead

Fixes https://github.com/fern-api/fern/issues/387

https://github.com/fern-primer/primer-api/actions/runs/3783614880/jobs/6432301003

I was surprised when it seemed like fern release ran, but it didn't.

I have a property that is a currency. I'm using the ISO 4217 three-letter standard (e.g. USD, EUR) and would like to be able to specify that in my Fern Definition.

countries is an list of string ISO 3166-1 alpha-2 which is a

List of countries in ISO 3166-1 alpha-2 format covered by this coverage configuration.

Example: ["DE","FR","US"]

Today in Fern, the most specific I can get is string.

Context: OpenAPI supports this and renders it in Stoplight docs. (Example https://developers.gigs.com/docs/api/bc5c988e713ed-list-all-plans#response-body )

TODO:

• [x] Handle $ in existing fern check rules
• [ ] Add fern check rule for non-existing reference
• [ ] Add fern check role for duplicate example names

https://github.com/ravenappdev/raven-api/pull/31/commits/b1db4aba4dda30a9e89883ebcff211e04123f273

The migration moved Device in-line for a request. I reference that type multiple times in the API definition and thus failed fern check now. It feels like the migration caused me a headache to go figure out how to fix this.

As a user, if I add custom files to the repo, it would be nice have a reminder from Fern that they need to be added to .fernignore or else they'll be overwritten.

An example is adding a GitHub Action and then forgetting to add .ferignore so my file is deleted: https://github.com/fern-primer/primer-openapi/commit/a7cff3d9072538ce21e8d547bd3b7a38e64d9438

for server-side API development I think we should focus on server side interfaces earlier and explain why they are different from server side stubs . I think we need to explicitly talk about how generated code and written code can live in separate places and not conflict.