Add Fern OpenAPI generation and openapi-fern.yaml artifact

README.md

@@ -6,9 +6,11 @@ This repo is actively maintained by Dropbox Sign's API Engineering team, but you
 
 ## Overview
 
-Dropbox Sign's [API Reference Documentation](https://developers.hellosign.com/api/reference/overview/) is built using [openapi.yaml](openapi.yaml) and the SDKs are built using [openapi-sdk.yaml](openapi-sdk.yaml). Both of those files are **generated** as part of a build process. 
+Dropbox Sign's [API Reference Documentation](https://developers.hellosign.com/api/reference/overview/) is built using [openapi-fern.yaml](openapi-fern.yaml) (Fern-ready, self-contained) and the SDKs are built using [openapi-sdk.yaml](openapi-sdk.yaml). Both of those files are **generated** as part of a build process. 
 These are the main parts of this repo you'll need to know about:
 - [openapi-raw.yaml](openapi-raw.yaml) -- The functional implementation of the Dropbox Sign API as an OpenAPI spec. This file reflects all public-facing work from Dropbox Sign's API Engineering team and is kept up-to-date.
+- [openapi.yaml](openapi.yaml) -- Translated documentation spec with relative file references (useful when browsing this repo locally).
+- [openapi-fern.yaml](openapi-fern.yaml) -- Self-contained documentation spec consumed by [sign-api-documentation](https://github.com/hellosign/sign-api-documentation) and Fern. Generated by `GenerateFernOas.php` during `./build`.
 - [/translations/en.yaml](translations/en.yaml) -- Contains all copy used for the API reference documentation. That includes descriptions for endpoints, parameters, schemas, and more. 
 - [/examples/json](examples/json) -- Contains example request and response payloads for the Dropbox Sign API.
 - [/examples](examples) -- Contains SDK-specific example requests for each endpoint.
@@ -225,6 +227,6 @@ Our source of truth is the [openapi-raw.yaml](openapi-raw.yaml) file. Everything
 
 This script replaces translation placeholders with their human values.
 
-It generates the [openapi.yaml](openapi.yaml) file which is used for our public documentation, and generates the [openapi-sdk.yaml](openapi-sdk.yaml) file which is very similar to [openapi.yaml](openapi.yaml) but has had directives that are incompatible with the [OpenAPI Generator](https://openapi-generator.tech/) tool removed.
+It generates the [openapi.yaml](openapi.yaml) file, the [openapi-fern.yaml](openapi-fern.yaml) file used by Fern documentation, and generates the [openapi-sdk.yaml](openapi-sdk.yaml) file which is very similar to [openapi.yaml](openapi.yaml) but has had directives that are incompatible with the [OpenAPI Generator](https://openapi-generator.tech/) tool removed.
 
 Any changes to our OpenAPI specification _must_ first go through [openapi-raw.yaml](openapi-raw.yaml) to ensure necessary data trickles down to the correct tools.

bin/generate-oas.php

@@ -35,3 +35,7 @@
     $generate = new Hello\OpenApi\GenerateSdkOas(true);
     $generate->run();
 }
+
+echo "\nCreating Fern-specific OpenAPI file ...\n";
+$generate = new Hello\OpenApi\GenerateFernOas();
+$generate->run();

examples/json/SignatureRequestFilesResponse.json

@@ -1,4 +1,4 @@
 {
-  "file_url": "https://s3.amazonaws.com/hellofax_uploads/super_groups/2016/03/18/9aba07a585d7e223b4f137c8981c5e5892893c00/merged-completed.pdf?AWSAccessKeyId=AKIAJWEWDFQHQMBECJZA&Expires=1452868903&Signature=M%2FNDS%2BQre8xjPvzm7fHf%2BjO8Zbc%3D",
+  "file_url": "https://s3.amazonaws.com/hellofax_uploads/super_groups/2016/03/18/9aba07a585d7e223b4f137c8981c5e5892893c00/merged-completed.pdf?AWSAccessKeyId=EXAMPLE_ACCESS_KEY_ID&Expires=1452868903&Signature=EXAMPLE_SIGNATURE",
   "expires_at": 1458605123
 }

examples/json/TemplateFilesResponse.json

@@ -1,4 +1,4 @@
 {
-  "file_url": "https://s3.amazonaws.com/hellofax_uploads/super_groups/2016/03/18/9aba07a585d7e223b4f137c8981c5e5892893c00/merged-completed.pdf?AWSAccessKeyId=AKIAJWEWDFQHQMBECJZA&Expires=1452868903&Signature=M%2FNDS%2BQre8xjPvzm7fHf%2BjO8Zbc%3D",
+  "file_url": "https://s3.amazonaws.com/hellofax_uploads/super_groups/2016/03/18/9aba07a585d7e223b4f137c8981c5e5892893c00/merged-completed.pdf?AWSAccessKeyId=EXAMPLE_ACCESS_KEY_ID&Expires=1452868903&Signature=EXAMPLE_SIGNATURE",
   "expires_at": 1458605123
 }