Skip to content

SmartBear-DevRel/SmartBearCoin-Portal-Automation

 
 

Repository files navigation

SwaggerHub-Portal-Management

This repository demonstrates how to automate the deployment of products and product content to be published to a SwaggerHub Portal instance 🚀

This bootstrapped repository is setup with 3 sample products which will be deployed and optionally auto-published.

  • A sample "Adopt a Pet" product exists in this folder
  • A sample "SwaggerHub Portal APIs" product exists in this folder
  • A sample "Zephyr Squad APIs" product exists in this folder

Each product has varying number of pages, images, content nesting etc.

Getting Started

To leverage this automation process for your own SwaggerHub Portal, the recommended process is as follows:

  • Fork this repo to your local GitHub profile/organization
  • Create the appropriate folders and content underneath the products folder following the conventions laid out below.
  • Setup the required repository secrets, environment(s), and environment variables needed by the configured GitHub Actions.
  • Delete the boilerplate products folders: "Adopt a Pet", "SwaggerHub Portal APIs", and "Zephyr Squad APIs".
  • Run the GitHub Actions to validate and publish your content.

Conventions

The automation works by uploading content structured in accordance with the following conventions.

Folder / File Structure Conventions

The following product structure must be adhered to allow for the automation to process the products and content:

  • products folder- a folder containing all products to be uploaded and published. Each product sub-folder name will be used as the product name created/modified within the portal
    • product One folder - contains all data relevant to "Product One"
      • *.md files - contains the markdown documents to be published within "Product One". The file name is used as the table-of-contents entry name.
      • images folder - a folder to house the product logo and embedded sub-folder
        • *.png / *.jpeg - a root level image to be used as the product logo (needs to be reference from the manifest.json)
        • embedded folder - a folder to storing all images to be embedded within the product markdown pages. See Image Embedding Conventions for more info on how to reference.
      • manifest.json - stores product metadata (like description, slug, logo url, visibility, etc.) and content metadata (like table of contents order, page nesting, etc.)
    • product Two folder ...
    • product N folder ...

Image Embedding Convention

The automation process will first publish all product images and then use the published metadata to replace image link placeholders within the markdown content.

The convention is as follows:

![image-filename-including-file-extension](relative path to image in the ./images/embedded folder)

An example of how an image should be referenced in the markdown is as follows:

![Sample-Portal-Landing-With-Product.png](./images/embedded/Sample-Portal-Landing-With-Product.png)

OpenAPI References in Markdown Convention

The OpenAPI references are predictable based on your known SwaggerHub Portal sub-domain.

The convention for embedding a link to a specific OpenAPI operation within a markdown page is as follows:

[link text of your choice](https://<YOUR-SWAGGERHUB-SUBDOMAIN>.portal.swaggerhub.com/swaggerhub-portal/default/<API-SLUG>#/<OPENAPI-TAG-CONTAINING-OPERATIONAL-IF-APPLICABLE>/<OPENAPI-OPERATION-ID>).

So you will replace the following parameters which are all known up front:

  • YOUR-SWAGGERHUB-SUBDOMAIN - the sub-domain used by your portal instance
  • API-SLUG - the slug defined for your API content (defined in the relevant manifest.json)
  • OPENAPI-TAG-CONTAINING-OPERATIONAL-IF-APPLICABLE - if your operation is nested under a tag then you should define the link with the appropriate tag name
  • OPENAPI-OPERATION-ID - the operationId of the path item object within the API you want to reference from the markdown

An example of how an operation reference should be embedded in the markdown is as follows:

Check out the products operation at [`/products`](https://frankkilcommins.portal.swaggerhub.com/swaggerhub-portal/default/swaggerhub-portal-api#/Products/createProduct).

Table of Contents Conventions

The table of contents is completely driven by the manifest.json file contained within each Product folder. The specified manifest file MUST validate against mainfest.schema.json.

A sample manifest is as follows:

{
    "productMetadata": {
        "description": "This product gives the ability to programmatically embedded a Pet adoption workflow into your application 🐶",
        "slug": "pet-adoptions",
        "public": true,
        "hidden": false,
        "logo": "images/AdoptionsAPI.png",
        "logoDark": "",
        "autoPublish": true,
        "validateAPIs": true
    },
    "contentMetadata": [
        {
            "order": 0,
            "parent": "",
            "name": "Getting Started with Pet Adoptions",
            "slug": "getting-started-with-pet-adoptions",
            "type": "markdown",
            "contentUrl": "Getting-Started-With-Pet-Adoptions.md"
        },
        {
            "order": 1,
            "parent": "getting-started-with-pet-adoptions",
            "name": "Client Code (C#)",
            "slug": "client-code-csharp",
            "type": "markdown",
            "contentUrl": "Client-Code-Csharp.md"
        },
        {
            "order": 2,
            "parent": "getting-started-with-pet-adoptions",
            "name": "Client Code (Typescript)",
            "slug": "client-code-typescript",
            "type": "markdown",
            "contentUrl": "Client-Code-Typescript.md"
        },
        {
            "order": 5,
            "parent": "",
            "name": "Pets API",
            "type": "apiUrl",
            "slug": "pets-api",
            "contentUrl": "https://api.swaggerhub.com/apis/frank-kilcommins/Pets/1.0.0/swagger.json"
        },
        {
            "order": 6,
            "parent": "",
            "name": "Adoptions API",
            "type": "apiUrl",
            "slug": "adoptions-api",
            "contentUrl": "https://api.swaggerhub.com/apis/frank-kilcommins/Adoptions/1.0.0/swagger.json"
        }
    ]
}

The productMetadata defines the following properties:

Property Description
description This property provides a description of the product. It explains what the product does and its purpose.
slug The slug is a unique identifier for the product. It is used in the URL and helps to identify the product in the portal.
public This property determines whether the product is publicly accessible or not. If set to true, the product can be accessed by anyone. If set to false, only authorized users can access the product.
hidden The hidden property determines whether the product is visible in the portal or not. If set to true, the product will be hidden from the portal. If set to false, the product will be visible.
logo The logo property specifies the path to the product logo image file. It is used to display the logo in the portal.
logoDark The logoDark property specifies the path to an alternative version of the product logo image file. It is used when a dark version of the logo is needed.
autoPublish This property determines whether the product should be automatically published after deployment or not. If set to true, the product will be published automatically. If set to false, the product will not be published automatically.
validateAPIs This property determines whether API standardization rules should be ran against the API to determine conformance with organizational rules.

The contentMetadata defines the following properties:

Property Description
order The order in which the content should appear in the table of contents.
parent The slug of the parent content, if the current item is to be nested under a parent item.
name The name of the content page.
slug The slug is a unique identifier for the content. It is used in the URL and helps to identify the content in the portal.
type The type of the content. It can be either "markdown" or "apiUrl".
contentUrl The URL or file path of the content. For markdown content, it is the path to the markdown file. For API content, it is the URL of the Swagger/OpenAPI specification as published in SwaggerHub

GitHub Actions

This repo comes with a simple boilerplate action that can be triggered manually or upon merge into the main branch.

The action requires the following repository secrets to be configured:

  • SWAGGERHUB-API-KEY - an API key associated to a user with the appropriate permission to be able to publish Portal content. See Portal User Management for more info.

The action requires the following repository environment to be configured:

  • Production - the default environment. Feel free to configure additional environment and adjust the action as required if applicable for your use case.

The action requires the following repository environment variables to be configured:

  • SWAGGERHUB_PORTAL_SUBDOMAIN - the sub-domain used by your portal
  • SWAGGERHUB_ORG_NAME - the SwaggerHub organization housing the APIs and standardization rules

Docs as Code PR Commit Validation Action

This action runs on every commit and every PR to validate the contents and structure of the content to be published to the portal

The action performs the following jobs:

  1. spell-check: Performs spell checking on all of the markdown files under the products folder (note to add a list of known good custom words update the ./custom-words.txt file)
  2. validate-manifests: Performs a JSON Schema validation check against the defined product manifest.json files to ensure they are correctly specified.
  3. lint-api: Performs API standardization checks against each API referenced by a product manifest.json file. There is the ability to skip API validation for a specific API product via the productMetadata in the manifest.json.

Docs as Code Action

This action runs on upon merging into main. It performs all the checks as per above and assuming all validations pass, it then runs then publishes the content to the appropriate SwaggerHub Portal instance.

The action performs the following jobs:

  1. spell-check: Performs spell checking on all of the markdown files under the products folder (note to add a list of known good custom words update the ./custom-words.txt file)
  2. validate-manifests: Performs a JSON Schema validation check against the defined product manifest.json files to ensure they are correctly specified.
  3. lint-api: Performs API standardization checks against each API referenced by a product manifest.json file. There is the ability to skip API validation for a specific API product via the productMetadata in the manifest.json.
  4. publish: Publishes all of configured products into the referenced SwaggerHub Portal instance.

About

Little repo to store docs and artifacts used to hydrate my SwaggerHub Portal instance

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • Shell 100.0%