Browsing Documentation
Shape Docs reads OpenAPI specifications from repositories hosted on GitHub. This ensures that OpenAPI specifications are under version control and can be peer-reviewed by all team members, facilitating spec-driven development. Team members must have access to a GitHub repository to view and edit the OpenAPI specification.
Shape Docs utilizes GitHub for access management, requiring users to authorize with GitHub. Consequently, Shape Docs only displays documentation residing in repositories that users have access to on GitHub.
The first page you see upon opening Shape Docs is the login page. Authorize and log in with your GitHub account.
After logging in with your GitHub account, you will be presented with a list of projects you have access to. Each project in the list corresponds to a repository on GitHub.
Since Shape Docs reads documentation from Git repositories on GitHub, it can show the documentation on each branch and tag within a repository. You can select the branch and tag in the upper-right corner of the page. Shape Docs refers to branches and tags as versions.
Some versions may contain multiple OpenAPI specifications, such as one for each service in a microservice architecture. These specifications will be in different files within the repository. You can select the specification to view in the upper-right corner.
Note that the list of specifications may change depending on the selected branch or tag.
Shape Docs supports the Swagger, Stoplight, and Redocly viewers. You can choose your preferred viewer from the dropdown next to your name in the lower-left corner. This setting is persisted locally.
