This repository contains all source material used for HelloSign's API Reference Documentation and official SDKs (work in progress, currently in beta). The docs and SDKs are both powered by the OpenAPI spec, which also keeps them in sync with our API development.
This repo is actively maintained by HelloSign's API Engineering team, but you can help us improve these resources for everyone by contributing.
The state of tooling based on this repo:
- HelloSign's API reference documentation - launched in production.
- HelloSign SDKs - available in beta only. See the "openapi" branch of your preferred SDK.
Warnings:
- Think twice before using the OpenAPI-powered SDKs for anything critical.
- The interfaces may change without warning. Backwards compatibility is not yet guaranteed nor implied.
HelloSign's API Reference Documentation is built using openapi.yaml and the SDKs are built using 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 -- The functional implementation of the HelloSign API as an OpenAPI spec. This file reflects all public-facing work from HelloSign's API Engineering team and is kept up-to-date.
- /translations/en.yaml -- Contains all copy used for the API reference documentation. That includes descriptions for endpoints, parameters, schemas, and more.
- /examples/json -- Contains example request and response payloads for the HelloSign API.
- /examples -- Contains SDK-specific example requests for each endpoint.
Note: Our API reference documentation supports having multiple examples for requests, responses, and SDK implementations for every endpoint. But we need your help to get there! Contributions that help us grow our example coverage are highly valuable at this stage.
We accept contributions and feedback that help us provide a better a developer experience for users of the HelloSign API. Our OpenAPI-based tooling relies on multiple build processes, and this repo contains multiple directories that may seem confusing at first but allow us to more easily manage a single source of truth (openapi-raw.yaml) and several tightly-coupled SDKs.
A complete contribution workflow would look like the following:
Clone repo and create branch with unique name (i.e. sig-request-java-sample).
The vast majority of users will not need to make any changes to our OpenAPI specification. If you notice any issues with the spec itself, feel free to open a GitHub issue to allow us to address the problem.
For a detailed explanation of how our openapi-raw.yaml, openapi.yaml, and openapi-sdk.yaml files relate to each other and how they are used in the build process, please go to the openapi-raw.yaml Explanation section.
To make copy changes look up the translation placeholder value using the openapi-raw.yaml file.
Translation placeholders are prepended with _t__ for easier identification:
info:
title: '_t__OpenApi::TITLE'
description: '_t__OpenApi::DESCRIPTION'
termsOfService: 'https://www.hellosign.com/terms'The placeholder corresponds to a value in the /translations/en.yaml file, without the _t__ portion. For the _t__OpenApi::TITLE placeholder the matching translation would be:
"OpenApi::TITLE": Dropbox Sign APISome translation values are references to other files, like so:
"OpenApi::TAG::ACCOUNT::DESCRIPTION": ./markdown/en/tags/account-tag-description.mdThe matching file can be found at markdown/en/tags/account-tag-description.md and any changes should be made directly against that file's contents.
To apply changes made against the translation file(s), simply run the build script. You will see the changes reflected on the openapi.yaml and openapi-sdk.yaml files.
Translation changes will affect all SDKs so you must rebuild them. See the Rebuilding SDKs section for more information.
Code samples for all our SDKs are located in the /examples directory.
Each endpoint has at least one example for each of our SDKs. The Node SDK has two examples (*.js and *.ts), and we also maintain cURL examples that can be used without our SDKs.
If you make changes to any of the code samples you should also rebuild the SDKs because examples are embedded in the documentation for each SDK.
If you make a change to only a single language you only need to rebuild that SDK, otherwise it is best to rebuild all SDKs. See the Rebuilding SDKs section for more information.
Any changes to translations/copy, or code samples, will require rebuilding the SDKs. Run the generate-sdks script to get started.
You can rebuild an individual SDK by running ./generate-sdks -t {SDK} where SDK is one of dotnet, java, node, php, python, ruby.
To rebuild all SDKs run ./generate-sdks -t all.
Changes will appear against the /sdks directory. Make sure to include these changes in your pull requests!
We generate our SDKs using the OpenAPI Generator tool. This tool reads the contents of the openapi-sdk.yaml file. It also reads related examples from the /examples directory and embeds the contents into the generated documentation.
If you notice a bug in the generated code you can open a GitHub issue against this repo, or fix it yourself and submit a pull request!
Changes must be made against the mustache files located with the templates directory for each SDK:
- /sdks/dotnet/templates
- /sdks/java/templates
- /sdks/node/templates
- /sdks/php/templates
- /sdks/python/templates
- /sdks/ruby/templates
You can then run the generate-sdks script to see your changes applied. See the Rebuilding SDKs section for more information. This script also automatically runs each SDK's unit test suite.
If you make changes to any of the SDKs you are able to try out your changes locally by using the /sandbox directory. Within this directory we have created the minimum files and configs necessary to allow you to test a local copy of each SDK. The exact method depends on the SDK language but it mostly involves generating an archive that each SDK's package manager can consume.
To begin run the generate-sdks script to rebuild your SDKs locally. See the Rebuilding SDKs section for more information. This will copy the necessary data into each SDK's /sdks directory.
Next, for the C#, Java, Node, or PHP SDKs run the correct script:
- C# -
./bin/sandbox-dotnet - Java -
./bin/sandbox-java - Node -
./bin/sandbox-node - PHP -
./bin/sandbox-php
Both Python and Ruby do not need to generate an archive, they can read directly off of the local filesystem.
You can now use your favorite IDE to open the correct sandbox directory as a new project.
- C# - /sandbox/dotnet
- Java - /sandbox/java
- Node - /sandbox/node
- PHP - /sandbox/php
- Python - /sandbox/python
- Ruby - /sandbox/ruby
Use GitHub issues to report problems or gaps in our documentation, request sample coverage for a specific API feature, or ask for an update to an endpoint description that you think needs attention. Any feedback that will help us create a better experience in our documentation is appreciated.
We welcome pull requests with enhancements to copy or examples in our API reference documentation. Please follow the development flow for submitting PRs. The table below contains information about the types of pull requests we're able to support:
| Type of PR | File(s) to change | Merge requirements |
|---|---|---|
| Changes to existing code examples |
|
No local build process needed before PR |
| Adding new code examples |
|
User must manually add reference to new examples in the openapi-raw.yaml file then generate new OpenAPI spec before submitting PR |
| Copy changes: descriptions for endpoints, parameters, schemas, or properties | /translations/en.yaml | User must generate new OpenAPI spec before submitting PR |
This repo is published under the Apache 2.0 license. Please see LICENSE for more information.
There's a wide world of APIs out there and we (HelloSign's API Engineering team) wanted to thank you for using ours. We've been working hard to improve our developer experience and have some big releases planned for this year (2022). We look forward to showing you that your trust is well placed.
Additional information about this repo, OpenAPI, and/or related tooling. May not be sequential.
The API Engineering team at HelloSign adopted the OpenAPI specification in order to provide a better experience to HelloSign developers in a way that was scalable and sustainable. We're using it as the source of our API Reference Documentation and SDKs, which means both tools stay in total parity with the HelloSign API.
The SDKs based on our OpenAPI spec are a work in progress and none have moved past beta quite yet. They're currently available as an "openapi" branch in each respective repo.
| Link to SDK | Status |
|---|---|
| NodeJS |  |
| PHP | |
| C# dotnet | |
| Python | |
| Ruby | |
| Java | |
Note: You can help us accelerate the launch of an SDK by being an early adopter. Please jump right in and start using it, then open an Issue in that SDK's GitHub repo when you find something that needs to be fixed.
Our source of truth is the openapi-raw.yaml file. Everything else is built from this file. However it cannot be used directly by our documentation provider nor can we build SDKs from this file. For that we have created our build script.
This script replaces translation placeholders with their human values.
It generates the openapi.yaml file which is used for our public documentation, and generates the openapi-sdk.yaml file which is very similar to openapi.yaml but has had directives that are incompatible with the OpenAPI Generator tool removed.
Any changes to our OpenAPI specification must first go through openapi-raw.yaml to ensure necessary data trickles down to the correct tools.