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

Please use ANSI-92 SQL Join Syntax

-
Image
Way back in 1992, a standard was published for SQL. In it, the syntax for specifying joins in SQL Database was finally standardized. This was a good thing because (for folks who've been doing this a while), trying to decode the vagaries of how various Databases handled outer joins could drive you bonkers yielding different results depending on the parse order of things in the from and where clauses. Unfortunately, some DBMS vendors took a while to adopt this standard (Oracle didn't support it until 2001), but at this point if you're using a major RDBMS and NOT using it, you're probably mired in a tradition or habit that bears changing. As an example of what I'm describing, here are some examples of what I mean. Old School (no standard syntax + implementation and evaluation of predicates varied by vendor [and query]): select * from customer, order where customer.customer = order.customerid ANSI way (agreed to standard, predicate evaluation has some rules ...
Read more

webxr with Babylonjs, A-frame/Threejs, and Unity

-
I've been working quite extensively on a webxr side project. Originally it was built with a-frame / threejs. You can take a look at it here at Immersive Idea . Recently I relized I was "fighting the framework" more than I was "getting things done". Originally, I chose a-frame because it was essentially a "no code" (well just html markup) way to build scenes. Additionally it's ECS framework was very well documented and easy to use. In an effort to broaden my perspective I started looking at alternatives (Unity with OpenXr, Babylonjs) as I was struggling to keep the pieces working together. This is my (slightly long) recap of my observations. A-Frame A-frame is wonderful...it is well documented, easy to use, and the community is super friendly and helpful. If I simplly wanted to render scenes in webxr with minimal ability to manipulate the environment, I wouldn't even think twice about using it.... Heck I still use it for quick m...
Read more