OpenAPI Generator

The OpenAPI generator tool generates OpenAPI documents from scratch based on the prompts that you provide.

The OpenAPI generator tool can be used to generate OpenAPI 3.0 documents in JSON or YAML format from scratch based on prompts that are provided by the user that uses Natural Language Processing (NLP). Given a natural language description of an API or application as input that the user would like to generate an OpenAPI document for, the tool uses the Granite 3 model available on IBM watsonx to generate a starter stub of an OpenAPI document that the user can then take and continue to build on.
Note: The tool generates an OpenAPI documents from a natural language description, whereas the OAS creator tool generates the OpenAPI documents from an existing database schema that added to the API Agent sources.

Tool details and limitations

The following are the Open API Generator tool details and limitations:
  • This tool is provided to assist users with the task of generating an OpenAPI document from scratch based on a natural language description, it should not be confused with the OAS creator tool, also available to the API Agent, which is used for generating an OpenAPI document from an existing database schema added to the API Agent sources.
  • This tool relies on the Granite 3 foundation model available IBM watsonx for OpenAPI document generation.
  • Given that this tool relies on the output of the foundation model based on the provided input description, like all AI models, the output is subject to errors.
  • If the generated OpenAPI document does not match the description that is provided as input, try again and consider rephrasing the description.
  • If the generated OpenAPI document that is displayed from the model contains errors, such as OpenAPI specification errors, or semantic errors, the tool automatically passes the document through the fix (auto-correct) operation of the OpenAPI Enhancer tool. If still errors are present after this correction, these will be reported in the chat window.

  • If the generated OpenAPI document contains JSON or YAML syntax errors that cannot be fixed (auto-corrected) by the OpenAPI Enhancer tool, the tool does not display the document. In this situation, the system displays the following message: please re-phrase and try again. Try rewording the input description before trying again, such as using a different ordering or combination of words in the input prompt.

  • All OpenAPI documents that are generated by this tool should be reviewed for correctness and accuracy before being used.

Generate an OpenAPI document from a natural language description

You can generate an OpenAPI 3.0 document from scratch in either JSON or YAML format, from a natural language description given in English (one or more sentences) for the API or application that you would like to generate. Simply start your chat prompt with Generate an openapi for.... The generated OpenAPI document contains component schemas relevant to the API or application that is described, and path items for create, retrieve, update, and delete operations for those schemas. Also, the generated document includes recommended operation-level security and security schemas by default, unless explicitly prompted not to do so.

Note: Break the prompt as multiple meaningful sentences. You can mention the type of API you want to generate in the first sentence and the required specifications in the following sentences.

This operation shows with the following details: The generated OpenAPI 3.0 document in JSON or YAML format (By default, if the YAML format not specified in the input prompt message) that can be downloaded.

Table 1. Parameters
Parameter Required Description Default
text Yes The natural language description of the OpenAPI 3.0 specification to be generated
Note:

The entire input prompt message is used as the text parameter value. It does not need to be referenced explicitly.

 None
file_format No The Open API Generator tool supports the output format of the generated OpenAPI document file in JSON and YAML. YAML
Example prompts
Generate an OpenAPI spec for a weather application

Generate an OpenAPI spec for a book library application

Generate an openapi for a blog application in yaml format

Generate an OpenAPI spec for a blog application. Include operations for searching for blogs by most recommended topics. Searching for blogs should not require any authentication

Generate an OpenAPI spec for a weather application. Include an operation to provide a 7-day forecast for a given location

Genrate an OpenAPI spec for a book library application. Include operations to add and remove books from the library. Also include an operation to search the books in the library with a title

Next action suggested

  • Generate fastapi server code for the openapi file {@filename}
  • Generate fastapi server code with database integration for the openapi file {@filename}