Code Quickstart

Using this quickstart guide, you'll generate code for an API project using the Blackbird CLI.

Generating client or server code from an API specification allows you to interact with your API more efficiently during development and testing. By automating the creation of request and response handling, you can test endpoints without manually coding requests, saving time and reducing errors. If errors occur during code generation, you can refine the API specification to ensure it's complete and accurate.

Prerequisites

Before you get started:

• Download the CLI. For more information, see Download the CLI and log in.
• Add or create an API. For more information, see Add an API.
• Open your preferred IDE, such as Visual Studio Code.
• Install Docker. For more information, see Get Docker.

Generating code

After you have an API in the Blackbird catalog, you can generate code for the simple API project. Blackbird uses OpenAPI Generator to generate client or server code for the API description. For the purpose of this quickstart guide, you can use the go-server server template. However, you can also reference any of the available client or server generators. For more information, see the OpenAPI Generators List.

To generate code:

1. Run the code generate command.
2. The CLI prompts you for variables. Provide the package version and package name.When the simple API project is generated, it creates a new directory with all the necessary modules and Go files for the projects, including the Dockerfile you'll use to run and debug the code.

Running and testing the code locally

Using the new simple API project, run the code locally and curl the say-hello endpoint.

To run and test the code locally:

1. Run the following command.

2. In go.mod, replace module // with module github.com/your-username/simple-api or another module name of your choice. Then, in main.go, replace simple_api "///go" on line 17 with github.com/your-username/simple-api/go.

   Although you curled the endpoint, you'll need to containerize the code to implement the say-hello endpoint.

Containerizing the code

After the project runs locally, you can fix the unimplemented say-hello endpoint by using a combination of the code run and code debug commands. You'll containerize the code, run it locally, and then intercept traffic to the API in a hosted environment.

To containerize the code:

1. Run the code run command.A Docker container spins up, so you can test the API code beyond localhost.
2. Run the following commands to verify the publicly available URL and curl the endpoint. If you followed the Mocking Quickstart Guide, you'll notice that the mocked hostname has been reused for the code instance.

Debugging the code

After you containerize the code, you can debug the say-hello endpoint using the code debug command.

To debug the code:

1. Edit the GetHello method in go/api_default_service.go to return the proper message.

2. Set up debugging in your IDE. If you're using Visual Studio Code, use the following launch.json file in the .vscode directory.

3. In the Dockerfile, we'll add a debug stage to build the code with debugging flags and run the dlv debugger. You can find the complete Dockerfile below.

4. Run the debug commmand.

   The API server starts listening and the go-simple-api server starts up.

5. Attach a debugger. If you're using Visual Studio Code, you can find the VSCode debugger under the Run tab.

6. Set a breakpoint in the code (for example, in the edited GetHello method).

7. Curl the say-hello endpoint to see that the breakpoint is hit.

Use the code run and code debug commands to develop using a hybrid model. Your teams can collaborate on code that runs on a user's machine using the public URL. You can also use the hybrid model in CI pipelines where a virtual machine (VM) checks out the code and starts a code run session.

Next Steps

After debugging the say-hello endpoint and ensuring the code works as expected, deploy the code in a more permanent environment. For more information, see Deployment Quickstart Guide.