Skip to main content

Custom code samples

Even though we generate a basic cURL code sample by default in your documentation, you might want to customize the example provided and share even more specific language code samples to your API consumers. This is why we added this custom property.

Use the x-codeSamples property inside an Operation OpenAPI object. The x-codeSamples property accepts an array of code sample objects which are defined as such:

PropertyTypeDescription
lang *StringCode sample programming language name.
labelStringA label which will be used as a title in the code sample bloc. Defaults to the lang value if not provided.
source *StringThe source code sample content.
info

Bump.sh relies on the Highlight.js lib to color your code. If your language is not supported, the source code will be displayed anyway, just without color syntax.

Example usage

The following screen capture shows the rendering of adding two code samples cURL and Ruby to your Operation.

x-codesamples.gif

This is done by adding the following x-codeSamples array to your API definition:

paths:
/users:
get:
summary: Retrieve a user
operationId: getUserPath
responses: [...]
parameters: [...]
x-codeSamples:
- lang: cURL
label: Custom cURL
source: |
curl \
--user "name:password" \
--request GET \
--url 'https://api.example.com/v1/users' \
--header 'Accept: application/json'
- lang: ruby
label: Ruby library
source: |
require "http"
 
request = HTTP
.basic_auth(:user => "name", :pass => "password")
.headers(:accept => "application/json")
 
response = request.get("https://api.example.com/v1/users")
if response.status.success?
# Work with the response.body
else
# Handle error cases
end