A couple of content pieces about OAS Tools

[ashryanbeats]

Hi OAS Tools community!

Just sharing a couple of things I've published/co-published recently about OAS Tools in case either are helpful or interesting. If you check either out, I'd love to hear your thoughts.

"OAS Tools deep dive!" on I'd Rather Be Scripting podcast

The podcast episode is here.

In the episode, we use the OAS Tools Quickstart as a path to discussing the tool's features, including:

• What an "entity resource" is
• Creating an OpenAPI document from an entity resource
• Creating a Node.js/Express server from an OpenAPI document
• Understanding the generated server entry point, controllers, and services
• Validating a server's adherence to an OpenAPI spec

... all with OAS Tools.

"Create an entity resource file for OAS Tools with Prisma" blog article

The article is here.

This is a quick article showing how to make an entity resource file with Prisma that can be used with OAS Tools to generate an Open API document and a Node.js/Express server.

[alesancor1]

I really enjoyed hearing your thougths in your podcast! There are some things I definitely have to take into account. It's always nice to hear other developer's opinion, that helps a lot to put things into perspective.

I'm curious about one of the things you mention on your whishlist, what do you mean with "Ensuring that generated service responses adhere to OpenAPI document schema"? From what I understand, it is refering to response validation, but the library already does that, maybe it is not clear enough in the docs😅.

Regarding documentation, I notice that many things were confusing or need more explanation, thanks for pointing that out, I'll take a look to the docs! Also, feel free to make PR to the docs (You can modify any page by clicking the "Edit this page on GitHub" link in the docs website).

The blog article is very interesting, it also helps to explain how entity resources can be declared and used to generate the OpenAPI document using Prisma, which is a library that you don't see pretty often when it comes to exploring use cases for accessing data with a NodeJS API.

Thanks a lot for taking the time exploring our tool! 😄

[ashryanbeats]

Thanks for checking them out and for your kind comments @alesancor1!

Some responses below.

---

what do you mean with "Ensuring that generated service responses adhere to OpenAPI document schema"?

There's probably a clearer way I could have phrased this. >< All I mean there is that currently, it seems that like all generated services come with the same mocked server response, regardless of what the OpenAPI document specifies as a response.

For example, if you have this in your OpenAPI document:

paths:
  /api/v1/users:
    get:
      description: Returns all users
      operationId: getUsers
      responses:
        200:
          description: User list
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/user'

You can see that the response schema is typed as an array.

However, if you generate a server with OAS Tools from this OpenAPI document, you'll get a service (in a file named apiv1usersService.js) with the following:

export function getUsers(req, res) {
    res.send({
        message: 'This is the mockup controller for getUser'
    });
}

This mock response returns an object, not an array. Which means the validator will complain at you right from the start 😊

To be sure, this is not a major headache at all—as the developer, I'm going to need to implement the response for my own app anyways. I just thought it might be a nice touch to mock the response as an array when the OpenAPI document specifies that's what the response will be.

---

I notice that many things were confusing or need more explanation
Also, feel free to make PR to the docs

All good! I've gotten everything I need so far, so I would say it's off to a nice start. I'll submit a PR if I think I've got something helpful to share. 😄

[alesancor1]

I see what you mean ,the server scaffolding definitely needs an upgrade. It actually comes from the older OAS-Generator, so I decided to keep it simple and let some things as they were designed initially. However, the project has evolved further from that initial concept and as you say there are many things that can be done to make the generated server adhere to the OpenAPI schema, I'll take notes!