Creating a REST API definition file

You can use the open application programming interface (API) definition file wizard to generate an Open API 3.0 file or an Open API 2.0 (Swagger 2.0) file to define a Representational State Transfer (REST) API. The wizard supports projects that target a Liberty server or a WebSphere® Application Server traditional server and use Web 2.5 and later. Support is only on Liberty for Open API 3.0.

1. Create a web project that targets a server.

   For more information about creating web projects, see Creating web projects.

2. Create an open API REST definition file by completing one of the following options:
   • Select File > New > Other and then select Open API Definition File in the REST API definition section.
   • Right-click a project and select New > Open API Definition File.
3. Select the type of JavaScript Object Notation (JSON) or YAML file that you want to create.
   The choices that include swagger.json and swagger.yaml files apply to version 2.0. The choices that include openapi.json and openapi.yaml files apply to version 3.0.
   • To create a file with all of the top-level Swagger elements that are needed, select Create a swagger.json template file or Create a swagger.yaml template file depending on the file type that you selected.
   • To create a file with sample contents for common definitions, such as GET, PUT, and POST, select Create a swagger.json sample file or Create a swagger.yaml sample file depending on the file type that you selected.
   • To create a file with all of the top-level open API elements that are needed, select Create an openapi.json template file or Create an openapi.yaml template file depending on the file type that you selected.
   • To create a file with sample contents for common definitions, such as GET, PUT, and POST, select Create an openapi.json sample file or Create an openapi.yaml sample file depending on the file type that you selected.
4. Select a location for the file that you are creating:
   • The following option is available for version 2.0: To work with Swagger annotations, select Generate as stub document (META-INF/stub directory).
   • The following option is available for version 2.0 and version 3.0 and is the option that is selected by default: If you are not working with Swagger annotations, select Generate as top level document (META-INF directory).
5. Click Finish.