Adding Documentation to Framna Docs

Each project in Framna Docs corresponds to a Git repository hosted on GitHub that contains one or more OpenAPI specifications that each document an API.

Framna Docs consumes documentation written in the OpenAPI specification, a specification that standardizes how APIs can be documented. OpenAPI specifications are written in YAML. If you are not already familiar with OpenAPI or YAML in general, you are encouraged to consult the OpenAPI’s Getting Started guide.

Let's add a project to Framna Docs.

Create a repository

Let's create a repository containing the documentation for a project called "Example". The documentation must be hosted in a repository that has a name ending with the suffix specified by the REPOSITORY_NAME_SUFFIX environment variable. We assume this is set to "-openapi", and as such, we'll create a repository named "example-openapi". Framna Docs will not pick up the repository if its name does not have the correct suffix.

Open the GitHub website and create a new repository named "example-openapi" as shown below.

Add an OpenAPI Specification

The next step is to push a file containing an OpenAPI specification to our newly created repository. This must be a YAML file. It can be named anything, but the file must have either the “.yml” or “.yaml” extension and must be located in the root of our repository.

The contents of the repository should look as below.

You can add all the OpenAPI specifications you would like to any branch or tag within the repository, and they will all show up in the portal. See the Browsing Documentation article for more information.

Customize the Project

By default, Framna Docs will use the repository name with the “-openapi” ending removed as the name of the project, and it will show a placeholder icon in the list of projects.

This can be customized by adding a configuration file to the root of the repository. The name of the file should match the one specified by the FRAMNA_DOCS_PROJECT_CONFIGURATION_FILENAME environment variable. We'll assume this is set to ".framna-docs.yml".

The configuration file can specify the name, icon, or both. Typically, you will want to specify both the name and icon so projects are easily identifiable in the portal. We will customize our project by pushing the following file named ".framna-docs.yml" to the root of our repository.

name: Example
image: icon.png

The image property specifies the path to an image file that is hosted within the repository, so we will upload an image named "icon.png" in the root of the repository. It is recommended to use JPEGs or PNGs that are rectangular and between 120 x 120 px and 240 x 240 px.

The contents of the repository should look as below.

Displaying Remote Versions and Specifications

Framna Docs can display OpenAPI specifications that are hosted on a third-party site. These specifications can be listed in the project configuration file within a repository. Specifications are associated with a remote version. A project configuration file can list multiple remote versions, and each version can have multiple specifications, as shown below.

If the spec cannot be made public, you may use IP whitelisting or basic auth to allow Framna Docs to access the spec.

IP Whitelisting

If you are on Framna's deployment, the following IPs should be whitelisted: 3.64.84.197 and 52.28.118.4. These are the IPs used by Framna Docs to fetch the documentation.

Basic Auth

Framna Docs supports basic auth for remote specifications. If you wish to use basic auth, a remote specification can list authentication information, as seen in the example below. Note that both the username and password must be encrypted with Framna Docs' public key before being stored in the configuration. You should encrypt your information on the /encrypt page (e.g., https://docs.framna.com/encrypt)

name: Example
image: icon.png
remoteVersions:
  - name: Production
    specifications:
    - name: Foo Service
      url: https://foo.example.com/api/swagger/v1/swagger.yaml
    - name: Bar Service
      url: https://bar.example.com/api/swagger/v1/swagger.yaml
    - name: FooBar Service
      url: https://foobar.example.com/api/swagger/v1/swagger.yaml
      auth:
        type: basic
        encryptedUsername: iOYpcgoScpY+CsueQB5bk/J34GmNZbUBzeh4Em46TbUCzdX0Iwp3XbODS6WuR+sh7j5p5wI...
        encryptedPassword: lChXZ+Qf6OoakRBKAho1cYhrQQ7vlx46K/8I3eL1VZDweun4vTXdpjL5x1bGDD170tyZagT...
  - name: Development
    specifications:
    - name: Foo Service
      url: https://foo-dev.example.com/api/swagger/v1/swagger.yaml
    - name: Bar Service
      url: https://bar-dev.example.com/api/swagger/v1/swagger.yaml

It is not necessary to include OpenAPI specification files in the root of your repository when using remote versions.