Document an API Endpoint

Each endpoint in DocStar is a page that holds the request definition and its documentation. You build it once, test it in the editor, and publish it as an interactive reference.

#

Before you start

Endpoints live in an API collection. When you create a collection, choose the API type, or import an API spec (see below). In other collection types the sidebar only adds regular pages. See Collections.

#

Create an endpoint

  1. In the sidebar of your API collection, click + (Add Page) at the top to add it at the root, or hover over a page and click + to add it under that page.
  2. In the Add to Collection dialog, choose Endpoint.
  3. A new endpoint named Untitled opens. Click the name in the breadcrumb to rename it.
  4. Type a short summary in the Write Description field under the header (up to 500 characters).
#

Define the request

  1. Pick the method: GET, POST, PUT, PATCH or DELETE.
  2. Enter the URL. You can use environment variables, for example {{BASE_URL}}/users/:userId.
  3. Fill in the tabs below the URL:
Tab What goes here
Params Query params (key, value, description). Path variables written as :name in the URL appear here too, under Path Variables.
Authorization No Auth, Basic Auth or OAuth 2.0. See Authorization.
Headers Request headers, each with an optional description.
Body none, raw (TEXT, JSON, XML, HTML, JavaScript), form-data (text or file values) or x-www-form-urlencoded.
Script Pre-Script and Post-Script code. See Scripts.

Use the checkbox on each row to include or leave out a param or header. Bulk edit lets you paste many rows as text.

Press Ctrl+S (Cmd+S on Mac) to save.

#

Describe body fields

For a raw JSON body on a saved endpoint, switch from Raw to Body Description. DocStar shows each field of your JSON with a Description box. What you write here appears next to the fields in the published reference.

#

Add sample responses

Sample responses show readers what the API returns.

  • After you click Send, click Add to Sample Response in the response panel to save the live response.
  • Or open the Sample Response tab and click Add Sample Response. Enter a Status, a Description and a Body, then click Submit.

The body must be valid JSON. You can edit or delete a sample response with the pencil and bin icons.

#

Save example requests

To keep a variation of the request, such as a different body, send it and click Save as Example Request. The example is saved under the endpoint in the sidebar.

#

Arrange the doc view

Switch the DOC toggle in the header to see the endpoint as readers will. In this view you can drag sections to reorder them and add free text with + Text Area or + Text Block (a highlighted note).

#

Publish the endpoint

  1. Click Preview to check the reader view.
  2. Click Publish (or press Ctrl+M / Cmd+M).

If DocStar finds what looks like a secret, such as a token, it shows a Sensitive Information Warning. Remove it before you publish. When you edit a published endpoint, your changes are saved as a draft. Readers keep seeing the last published version until you click Publish again. To take an endpoint down, open the more menu in the header and click Unpublish. See Publish Pages.

#

Import existing APIs

  • From a file: in the collection list, click Import collection, drop the file and click Import. DocStar accepts OpenAPI 3.x and Swagger 2.0 (JSON or YAML), Postman collections and DocStar exports. Each import creates a new API collection.
  • From cURL: paste a curl command into an endpoint's URL field. DocStar fills in the method, URL, headers and body.
#

Export

Open Settings in the collection sidebar, go to Collection Actions and use Export Collection. Choose DocStar for a full copy, or Open API for a spec file. An OpenAPI export drops versions and endpoint descriptions.

Built with DocStar