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:

Property Type Description
lang * String Code sample programming language name.
label String A label which will be used as a title in the code sample bloc. Defaults to the lang value if not provided.
source * String The source code sample content. 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.


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

      summary: Retrieve a user
      operationId: getUserPath
      responses: [...]
      parameters: [...]
        - lang: cURL
          label: Custom cURL
          source: |
            curl \
              --user "name:password" \
              --request GET \
              --url '' \
              --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("")
            if response.status.success?
              # Work with the response.body
              # Handle error cases