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] [OPTION]...
genoas [file | url] [--host host] [--title title] [--desc description] [--version version]

OPTIONS:
--host host
--title title
--desc description
--version version
--format ( yaml | json )
--target ( 3.0.0 | 2.0 )

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 Swagger Editor and import the generated oas.yaml file.

3. Review the API and try invoking an operation, for example, a GET operation.

Notes:
* Swagger Editor for OpenAPI 2.0 is available at http://editor2.swagger.io
* The latest Swagger Editor can be run using Docker:
* https://hub.docker.com/r/swaggerapi/swagger-editor/
- https://swagger.io/docs/specification/2-0/basic-structure/


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.

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

    Hello all,

    I want to let you know that the genoas utility now includes a --format option to generate json format instead of yaml format.

    Also the --target option can be used to generate a spec file using version 2.0 of the spec instead of 3.0.0.

    Enjoy,

    Edsel