In this demo, we will look at the generated OpenAPI Specification.
It's on screen now.
On the top,
we see the OpenAPI version of the specification and some
general information regarding the API, the title and the version.
This matches what we inputted when registering the services on the container.
The next part is a list of paths.
These relate to our API's resource URIs.
For each of these, one or more methods are defined.
For example, we see that we can get the authors.
We also see that we can get a specific author,
update it with PUT, and partially update it with PATCH.
Let's expand the node for getting one specific author.
We see a tags object.
These tags are used for logical grouping.
Swashbuckle adds the same tag for all actions on a controller.
Then we see the parameters.
These match the input parameters for our action,
in this case a required authorId of type guid,
which in OpenAPI lingo means a string with uuid format.
And now we have the potential responses.
We see we can get a 200 OK response from this action,
which seems okay, although it's not complete yet.
We will improve on this during the course.
The content of a successful response is then described
through the allowed media types.
Currently, text/plain and application/json seem to be supported,
but that is just a data format, of course.
The actual schema, ie, the type of data,
is described as a reference to, in this case,
#/components/schemas/Author.
Let's scroll down a bit because that's where we can find that.
Here we find the schema for an Author generated by
Swashbuckle from the Author DTO.
Let's scroll up again.
So at first sight, this looks quite okay,
but as we'll notice later on,
once we start working with more complex scenarios like
supporting vendor‑specific media types,
the potential content tags will start behaving weird.
Moreover, there's something else going on.
According to the generated specification,
getting a specific author can only return a 200 OK response.
If we have a look at the GetAuthor action on our controller,
we see this isn't correct.
This action can also return a 404 NotFound,
and that's just what we see by inspecting to GetAuthor action.
If you've worked with APIs before,
you know that a 500 internal server error or a 400 bad request is also
definitely a possibility for almost all resources.
And there's more.
Let's scroll down to the definition for posting,
in other words creating, a new book.
The generate specification here is just plain wrong.
Not only are their content types that shouldn't be there,
like json‑patch+json,
it also states that the only thing that can be returned
from a POST request is a 200 OK response,
and that is not correct.
If we have a look at the action for creating a book,
we see that it can return a 404 NotFound and a 201 CreatedAt, but not a 200 OK.
Moreover, 400 Bad Request,
500 Internal Server Error, and so on, are also potential
response status codes for this action.
So with that, we know what the basic structure of an OpenAPI spec looks like,
but we also know that we've got quite a bit of work ahead of
ourselves to improve this generated specification so it matches
the reality of what our API can do. Let's add a documentation UI in the next demo.