Sample program to generate an OpenAPI spec file from a catalog file - Documents - Mobile - Progress Community

Sample program to generate an OpenAPI spec file from a catalog file

The OpenAPI Specification (formerly known as the Swagger Specification) describes RESTful Web Services. The specification can be used to generate client and server programs as well as documenting the services.

The Data Service Catalog describes the prescriptive REST API in OpenEdge Data Services. This REST API is used by JSDO-based clients to access the OpenEdge backend.

This sample program takes a catalog JSON file as input and generates an OpenAPI Specification file that can be used with related tools such as the Swagger Editor.
Note: Use Progress Developer Studio for OpenEdge to create an OpenEdge Data Service with a catalog file. See the following document for information on how to create one:
  • https://community.progress.com/community_groups/openedge_kendo_ui_builder/m/documents/3363

Requirements

  • Recent version of Node.js and NPM

Installation

unzip genoas.zip
cd genoas
npm install

Usage

genoas [file | url]
genoas [file | url] [--host host] [--title title] [--desc description] [--version version]

Example

  1. Run genoas command for a catalog.json file:
    genoas http://oemobiledemo.progress.com/OEMobileDemoServices/static/CustomerService.json
    genoas SportsService.json --host http://oemobiledemo.progress.com/OEMobileDemoServices

    This step generates the specification into a file with extension .yaml.
  2. Access http://editor3.swagger.io and import the generated oas.yaml file.
  3. Review and the API and try invoking an operation, for example, a GET operation.

Swagger Editor showing generated spec

Related links

Comments
  • Sample program to generate an OpenAPI spec file from a catalog file

    Hi Ed,

    Just downloaded so that I could give it a try.

    It states "Reading Catalog file........"

    Then

    ERROR: Error: connect ECONNREFUSED 127.0.0.1:80

  • Sample program to generate an OpenAPI spec file from a catalog file

    Hello,

    The error message that you are seeing indicates that an HTTP connection to localhost port 80 failed.

    Is your catalog hosted at 128.0.0.1:80?

    How does your command line look like?

    Please let me know.

    Thank you and regards,

    Edsel

  • Sample program to generate an OpenAPI spec file from a catalog file

    Hi Ed,

    After reading your comment, I believe I realized the issue.

    If I copy a Catalog file into my PAS  /webapps/ROOT/static instance then it creates a "yaml" file.

    C:\work\Swagger\genoas>genoas abc:port/.../CountryBusinessEntity.json

    Reading catalog file 'localhost:8820/.../CountryBusinessEntity.json

    OpenAPI spec written to CountryBusinessEntity.yaml

    However, I did interpret the "genoas [file | url]" from the README file that I could run "genoas" against a local "catalog" file without the need of PAS.

    :) :)

  • Sample program to generate an OpenAPI spec file from a catalog file

    Hello,

    Many thanks for the feedback.

    Yes, you should be able to work with a local file.

    The command works fine with a local file with a relative path.

    The issue was when working with an absolute path. The code handled it as if it was a URL.

    I have updated the code to work with an absolute path to local files

    Please use the updated zip file.

    Thank you and regards.