Konnect Dev Portal Client

This repo is an open source reference implementation of a Konnect Developer Portal Client leveraging the Konnect Developer Portal Client API and JavaScript SDK.

The Konnect Dev Portal is a web application for developers to locate, access, and consume API services. The Dev Portal enables developers to browse and search API documentation, test API endpoints, and manage their own credentials.

In Kong Konnect, you have two hosting options for the Dev Portal web user interface: a cloud hosted Dev Portal with Konnect or a self-hosted, open source Dev Portal powered by Konnect APIs.

Check out the example app to get an idea of what this client app looks like out-of-the-box.

Self-hosted Dev Portal benefits

There are several benefits to keep in mind when deciding whether to use a Konnect-hosted or self-hosted Dev Portal. The self-hosted portal provides the following benefits:

• Fully customizable: Use the example frontend Dev Portal application as a starting point and then customize Dev Portal for your needs using the Portal API. You can also integrate the API specs with workflows tailored to your organization’s own processes.
• Hosting service choice: When you self-host, you also get to choose which hosting service you use to deploy your Dev Portal.
• Range of customization options: With the self-hosted Dev Portal, you determine how much you want to customize. You can choose to use the example application right out of the box or you can use the Portal API to have more fine-grained control.
• Configurable internationalization
• Automated front-end test suite powered by Cypress

With those benefits in mind, there is the hosting cost to deploy this single page portal and you may need developer/designer support to fully customize this modern web-application to meet your business requirements.

Getting started

Using the Project: Best Practices

Branches

1. Main Branch (main): The main branch serves as the default branch, and all commits and pull requests should be directed here. It represents the latest version of the project.

2. Release Branch (release): The release branch includes all the changes from the main branch, but its latest commit will always correspond to the latest release tag.

Choosing the Right Branch

When contributing or using the project, it is essential to understand which branch best suits your needs:

1. For Contributors:

• If you want to contribute any new features or bug fixes, please create a new branch based on the main branch. Name your branch descriptively (see the branch naming conventions - Open a pull request to merge your changes into the main branch. This allows the maintainers to review your code before merging it into the default branch.

2. For Users Who Want Frequent Updates:

• If you prefer to use the latest development version of the project, you should use the main branch directly, either in your fork or as a submodule of your project.

3. For Users Who Want Stable Releases:

• Use the release branch if you prefer less-frequent updates. - The release branch provides a production-ready version of the project at each tagged release. - It is recommended to keep your fork of the repository updated with the latest changes from the release branch.

Staying Updated

Whether you are contributing or using the project, staying updated is crucial:

• Regularly fetch and pull changes from the main branch to your local repository. This ensures that your work is based on the most recent codebase.
• If you are using the release branch, merge the latest changes from main into your fork periodically to keep it up-to-date with the latest releases.

By following these guidelines, both contributors and users can efficiently collaborate on and use the project, ensuring a smooth and productive development experience for everyone involved.

Prerequisites

• Kong Konnect account
  • You can Start a Free trial at: konghq.com
  • Documentation for Kong Konnect is available at: docs.konghq.com
• Yarn ^1.22.x

Install dependencies

yarn install --frozen-lockfile

Create local .env file

cp .env.example .env

Set VITE_PORTAL_API_URL value in your current environment i.e .env file or local environment, this should match either the Kong supplied portal URL ending in portal.konghq.com (for local development) or the custom hosted domain URL set in Konnect (for your deployed environment). Be sure to set the custom self-hosted UI domain to match the domain you will be serving the portal out of to avoid CORS issues.

For Development you can provide any portal API URL, it is proxied by Vite, so you do not need to set the custom client domain.

Run vite dev with

yarn dev #optional --verbose

Run tests with

yarn test:e2e

Public Directory

If you need to store assets (e.g. fonts, images, or icons), you can create a public directory at the root level of the repository and Vite will utilize it by default. For more information on when or how to use the public folder, visit here.

Building for production release

Build production bundle '(dist/)' for deployment with

yarn build

Contributing

Please take the time to become familiar with our standards outlined below. First and foremost please and comply with the standards outlined in the CODE_OF_CONDUCT.

Committing Changes

Please follow the following branch naming scheme when creating your branch: This repo uses Conventional Commits. Commitizen can be used to help build commit messages. Or you can utilize the installed version with any of the following commands:

yarn commit

Note:

To disable linting during the pre-push git hook (on your fork), you can either comment out the contents of the lefthook.yaml file or remove it, as well as uninstall lefthook from the package.json file.

i.e

$ rm lefthook.yaml
$ yarn remove lefthook

Branch naming conventions

Please follow the following branch naming scheme when creating your branch:

• feat/foo-bar for new features
• fix/foo-bar for bug fixes
• test/foo-bar when the change concerns only the test suite
• refactor/foo-bar when refactoring code without any behavior change
• style/foo-bar when addressing some style issue
• docs/foo-bar for updates to the README.md, this file, or similar documents
• ci/foo-bar for updates to the GitHub workflows or actions

Releases

This repo uses Semantic Release for automated releases once per week. The release is triggered by a GitHub Action on the main branch. The release is based on the commit messages, so please follow the Conventional Commits specification.

Spec Customization

If you need to add or remove languages to the code snippet languages, you can pass in an object to SpecDetails.

You may pass in a themeOverrides object to SpecDetails. Here is an example if you would like to override languages:

        <SpecDetails
          :theme-overrides="{
            languages: [
              {
                prismLanguage: 'bash',
                target: 'shell',
                client: 'curl'
              },
              {
                prismLanguage: 'javascript',
                target: 'javascript',
                client: 'xhr'
              },
              {
                prismLanguage: 'java',
                target: 'java'
              },
            ]
          }"
        />

The default languages are the following. They will be overridden by what you pass in to SpecDetails

      languages = [
        {
          prismLanguage: 'bash',
          target: 'shell',
          client: 'curl'
        },
        {
          prismLanguage: 'javascript',
          target: 'javascript',
          client: 'xhr'
        },
        {
          prismLanguage: 'python',
          target: 'python'
        },
        {
          prismLanguage: 'ruby',
          target: 'ruby'
        }
      ]

Translations guidelines

Join the Community

• Join the Kong discussions at the Kong Nation forum: https://discuss.konghq.com/
• Follow us on Twitter: https://twitter.com/thekonginc
• Check out the docs: https://docs.konghq.com/
• Keep updated on YouTube by subscribing: https://www.youtube.com/c/KongInc/videos
• Read up on the latest happenings at our blog: https://konghq.com/blog/
• Visit our homepage to learn more: https://konghq.com/

License

Copyright 2016-2023 Kong Inc.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.