Diagrams and API design with AI

Part 3 of a practical example of using AI for coding

This is part 3 of a multi-part series:

• In Part 1, we discussed setup and best practices and answered the question: “Will AI replace software developers?”.

• In Part 2, we designed a solution and created a design document.

• In Part 3, we will generate a sequence diagram and an OpenAPI specification.

Recap: URL Shortening Service

• We’re writing a solution for the URL Shortener Challenge.

• We’ve got a great design.

Visualizing The Design

Few things explain what software is supposed to do more than a sequence diagram.

• ChatGPT can’t currently generate images, but it can generate PlantUML text diagrams, and we can feed that into the online renderer (or, as I prefer, an IDE plugin) to get an image.

To visualize the design, I asked ChatGPT 4 (3.5 was not working out) to generate the diagram.

Write a PlantUML sequence diagram for the API interactions of the design below.

- Use descriptive aliases. Don't use one-letter aliases.
- Activate/deactivate each component in the sequence diagram when appropriate
- Separate use cases with section titles
- Use "actor" instead of `participant` for the user
- Include each record of the data model that we need to store

{complete design document}

---

That’s pretty good. You can also view the PlantUML source or an SVG.

API First

I like API First development.

• It helps to get everyone on the same page of what the API will be before any code is written.

• I use OpenAPI to describe APIs and share the specifications with team members.

• UI developers can start coding without the server, and server developers can start coding without a UI.

• When they’re both done, they integrate, and since the API was agreed upon first, it just works.

So let’s have ChatGPT generate the OpenAPI spec.

Your task is to generate an OpenAPI specification for API described in the 
design doc below.

- Included example requests and responses to cover the defined use cases.
- Provide example HTML errors in the spec.
- Use the PEP-8 standard for naming Python functions
- For the example domain, use `example.com`
- The error message should be in an `error` key
- Since we're using connexion, the operationId should point to the Python module 
  and function that will handle the request

{complete design document}

• Here ChatGPT 3.5 worked well.

• ChatGPT 4 provided more thorough results with better examples.

openapi: 3.0.0
info:
  title: URL Shortening Service
  description: Service to shorten long URLs.
  version: 1.0.0
servers:
  - url: https://example.com/
paths:
  /shorten:
    post:
      summary: Shorten a URL
      operationId: shorty.shorten_url
      requestBody:
        description: URL to shorten
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Url'
            examples:
              shortenUrlRequest:
                value:
                  url: "https://www.very-long-url.com/"

---

You can view the complete generated OpenAPI specification.

We’ll use this OpenAPI specification in our application development.

---

Next

Head to Part 4. Continue the journey.

• Part 1: Setup and Process

• Part 2: Design

• Part 3: Sequence diagram and API specification ← YOU ARE HERE

• Part 4: Generating tests

• Part 5: Generating the application and making it work