Services and Groups

A service is one API published to SelfDocHub. This page explains the services page, service groups and how administrators create and manage services.

Roles: Creating, editing and deleting services and groups, and rotating tokens, is for admin only. Everyone else sees the services of their teams.

The services page#

The home page (/) shows one collapsible block per service group. Each block holds a grid of tiles, one per service, in the group's own order. A tile shows:

  • the service name;
  • its endpoints counted per HTTP method;
  • the number of endpoints, tags and versions as small icons, and a badge with the documentation format;
  • the current version's number.

The collapsed state of a block is remembered in the browser. Users who are not administrators see only their teams' services and only groups that are not empty for them.

Creating a service#

Administrators get New Service and New service group buttons above the blocks. The service dialog takes:

  • a slug: lowercase letters, digits and single dashes, for example billing-api;
  • a name and a description (with a Markdown toolbar);
  • the main branch, which defaults to main;
  • the service groups it belongs to (the default group is always checked);
  • when creating, the teams that get access, and an optional specification file.

If you pick a file, it is published as the first version right after creation with the one-time token. If that publish fails (invalid document, oversized file), the service is still created and its token still shown, and only the publish is reported as failed. The token is shown in the dialog until you dismiss it, because it is never shown again.

Services can also be created with --register-service (see CLI Reference). Creating services is limited by your license's max_services.

Managing a service#

Clicking a service in the left menu opens its page (/docs/{slug}): name, description, endpoint counts per method, the Environments and Versions sections. For administrators the page adds:

  • Edit: name, description, main branch, groups.
  • Rotate Token: generates a new upload token and invalidates the old one. The new one is shown once.
  • Delete: asks for confirmation and removes the service from every group.

The description shown on the service page is the Markdown description of the service. Editors and administrators can replace it with an overlay without touching the specification. See Markdown Overlays.

Service groups#

Groups organize services into named, ordered sets. A service can be in several groups and then appears in each.

  • The default group, named "Все сервисы", always contains every service. It cannot be deleted, but it can be renamed and reordered.
  • Group names are unique, ignoring case.
  • The group dialog takes a name and the services, with Select all. In the default group only the name can be changed.
  • Every group has an icon chosen from a fixed set of about 60. It is shown in the left menu and in the group's block. The default is a folder.
  • A group can be hidden from the left menu. It then stays on the services page, marked with a crossed-out eye.
  • Administrators reorder groups and tiles by drag and drop or with arrow buttons. Hovering over a tile shows move, edit and delete buttons.

In the left menu, groups are the top level, each with its icon and a count of the services the user sees. When only one group is shown for a user, the group level is left out.

Next steps#

Screenshots

Last updated: