Generating swagger doc with copilot for undocumented rails app

-

Was taking a peek at how to do this and I took a stab.

Checked out gitlab project, fired up copilot and then (after a few iterations) hit upon this prompt:

  create a yaml file in openapi3 format that describes the methods and signatures of the 
  contollers/admin/applications_controller controller 
  assumes host are prod.myapi.com and stagin.myapi.com that host the api add 
  detailed descriptions in the summaryfields that explain edge cases and any 
  important side effects. Include list of tables accessed by api endpoints in the description. 
  Format list of tables like the following (tables => {table 1}, {table 2}). 
  Don't include character ':' in summaries, titles, or descriptions

and what I got was 

openapi: 3.0.0
info:
  title: Dashboard API (Accesses various resources)
  version: 1.0.0
servers:
  - url: https://prod.myapi.com
    description: Production server
  - url: https://staging.myapi.com
    description: Staging server
paths:
  /dashboard/application:
    get:
      summary: Get application details. Handles edge cases where the application is not found. Returns a 404 error if the application is not found (tables => {applications})
      operationId: getApplication
      responses:
        '200':
          description: Application details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Application'
        '404':
          description: Application not found
  /dashboard/groups:
    get:
      summary: List all groups. Handles edge cases where no groups are found. Returns an empty list if no groups are found (tables => {groups})
      operationId: listGroups
      responses:
        '200':
          description: A list of groups
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Group'
  /dashboard/labels:
    get:
      summary: List all labels with unique titles. Handles edge cases where no labels are found. Returns an empty list if no labels are found (tables => {labels})
      operationId: listLabels
      responses:
        '200':
          description: A list of labels
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Label'
  /dashboard/milestones:
    get:
      summary: List all milestones. Handles edge cases where no milestones are found. Returns an empty list if no milestones are found (tables => {milestones})
      operationId: listMilestones
      responses:
        '200':
          description: A list of milestones
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Milestone'
  /dashboard/projects:
    get:
      summary: List all projects. Handles edge cases where no projects are found. Returns an empty list if no projects are found (tables => {projects})
      operationId: listProjects
      responses:
        '200':
          description: A list of projects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Project'
  /dashboard/snippets:
    get:
      summary: List all snippets for the current user with pagination support. Handles edge cases where the page parameter is missing or invalid. Returns an empty list if no snippets are found (tables => {snippets}, {users}, {projects})
      operationId: listSnippets
      parameters:
        - name: page
          in: query
          required: false
          schema:
            type: integer
          description: Page number for pagination
      responses:
        '200':
          description: A list of snippets
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Snippet'
  /dashboard/todos:
    get:
      summary: List all todos for the current user. Handles edge cases where no todos are found. Returns an empty list if no todos are found (tables => {todos}, {users})
      operationId: listTodos
      responses:
        '200':
          description: A list of todos
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Todo'
components:
  schemas:
    Application:
      type: object
      properties:
        id:
          type: string
          description: Application ID
        name:
          type: string
          description: Application name
    Group:
      type: object
      properties:
        id:
          type: string
          description: Group ID
        name:
          type: string
          description: Group name
    Label:
      type: object
      properties:
        id:
          type: string
          description: Label ID
        title:
          type: string
          description: Label title
        color:
          type: string
          description: Label color
    Milestone:
      type: object
      properties:
        id:
          type: string
          description: Milestone ID
        title:
          type: string
          description: Milestone title
    Project:
      type: object
      properties:
        id:
          type: string
          description: Project ID
        name:
          type: string
          description: Project name
    Snippet:
      type: object
      properties:
        id:
          type: string
          description: Snippet ID
        title:
          type: string
          description: Snippet title
        content:
          type: string
          description: Snippet content
        author:
          type: string
          description: Snippet author
        project:
          type: string
          description: Associated project
    Todo:
      type: object
      properties:
        id:
          type: string
          description: Todo ID
        title:
          type: string
          description: Todo title
        completed:
          type: boolean
          description: Whether the todo is completed

All told, copilot is only "kinda ok" at actually generating code (other than boilerplate and/or well know things) and frankly I tend to try and "design them away". This, on the other hand is much more interesting to me. Inspecting and grokking existing code is very difficult and getting a leg up (obviously I still have to see how "correct" it is) on this kinda thing could be a more useful accelerator (for me).

Comments

Post a Comment

Popular posts from this blog

the myth of asynchronous JDBC

-
Image
I keep seeing people (especially in the scala/typesafe world) posting about async jdbc libraries. STOP IT! Under the current APIs, async JDBC belongs in a realm with Unicorns, Tiger Squirrels, and 8' spiders. While you might be able to move the blocking operations and queue requests and keep your "main" worker threads from blocking, jdbc is synchronous. At some point, somewhere, there's going to be a thread blocking waiting for a response. It's frustrating to see so many folks hyping this and muddying the waters. Unless you write your own client for a dbms and have a dbms that can multiplex calls over a single connection (or using some other strategy to enable this capability) db access is going to block. It's not impossible to make the calls completely async, but nobody's built it yet. Yes, I know ajdbc is taking a stab at this capability, but even IT uses a thread pool for the blocking calls (be default). Someday we'll have async databa
Read more

The difference between Scalability, Performance, Efficiency, and Concurrency explained

-
I thought I'd give some explanation of the difference between scalability, performance, Efficiency, and concurrency. To make things more accessible (and because I'm watching a cooking show on TV) I'm going to use a baking metaphor to help explain the differences. In our case, the system in question is baking cookies for consumers. Scalability, is how well something responds to adding more resources. If we can double our capacity by doubling the number of resources, we've got linear scalability. In our baking example, if we add more ingredients, we can scale to a larger number of cookies. To contrast with our other metrics, this doesn't actually increase the performance of creating a single cookie (they still take 10 minutes to bake), and the efficiency is the same (we just have more capacity). We also cannot bake more cookies in a fixed time period, but over a larger time period we can produce more cookies. Performance is how fast something can get done, u
Read more

Push versus pull deployment models

-
There are two deployment models: push and pull. In a "Pull" deployment model, the individual servers contact a master server, download their configuration and software, and configure themselves. In a "Push" model, a master server pushes the configuration and software to the individual servers and runs commands remotely. While neither technique is right or wrong, they both have some specific advantages and disadvantages that you should understand when making a decision. In the ruby hosting world, an example of a "push" deployment is heroku , while Engine Yard is an example of a "pull" type deployment. In the Pull model, each server has information about how to obtain it's configuration, when it boots (or whatever the configuration triggering event happens to be) it can continue to proceed without intervention from the master server. In the Push model, because the master server is orchestrating things, it will typically need to have a c
Read more