Lecture thumbnail 0:00 / 0:00 Swagger is an API documentation tool.
That means the developers should be in a
position to write comments or descriptions about each
and every endpoint.
But here, by default, no documentation is provided.
For example, for this API slash cities get
request, as a developer, I would like to
write some documentation comment.
And that should be appeared somewhere here, so
that I can explain the purpose of the
particular endpoint.
To do so, we have to enable documentation
comments in Swagger.
Let us see how.
First, step one, you have to add XML
documentation comments for your action methods.
For example, I would like to add documentation
comments for this get cities.
So right click on that particular method.
And under snippet, select insert comment.
It automatically generates XML documentation syntax in .NET.
The summary tag in XML documentation includes with
the description that explains the purpose of the
particular endpoint or method.
For example, we can write like.
So this is the sentence that explains the
purpose of the particular method.
Optionally, you can write the description about returns
that explains only the return value or return
type of the method.
It is optional.
In addition to that, if the method contains
one or more parameters, you can write the
documentation for each and every parameter of that.
Currently, I’m not writing because this method is
not having any parameters.
But by default, Swagger cannot read that particular
XML comment.
So the step two is we have to
convert this XML documentation comments into an XML
file within the same project.
In order to do so, right click on
the project.
I mean, right click on the Web API
project, go to project properties.
And here under build, select output.
Here you have an option called XML documentation
file path.
Here you have to mention the path of
your XML document.
For example, I am just writing API slash
XML.
So this will automatically create API slash XML
file within the current working project.
And that XML will be the input for
Swagger so that it can read the comments
from that XML file.
Let me show that.
Once you build the solution.
It automatically generates API slash XML in the
current working solution.
And it contains the current working assembly.
The corresponding get cities method.
And the summary what we have written there.
So the same comments are automatically added in
this XML file.
This is automatically generated by .NET, but not
by Swagger.
But Swagger can read this XML comments and
display the same in the Swagger UI.
But we have to tell the same to
Swagger.
So go to the program.cs file.
Now this is the step three.
While calling add Swagger gem in order to
generate open API specification, we have to ask
the Swagger to include those XML comments.
So you can add an options lambda expression.
So it provides additional options for the Swagger
generation.
And we have to ask, hey, Swagger, include
XML comments.
And it is asking us what is the
input part of the XML file that contains
the XML comments.
First, I would like to take the current
working folder path.
That is the app context dot base directory
represents the current working folder path up to
the current working project path.
That is the complete solution path and then
project name.
And then in the same folder, we have
a file API slash XML that we have
set in the project properties.
So at runtime, the current working project path
slash API slash XML.
That is the complete path of the XML
file and the Swagger can read the XML
comments from that file and can display the
same in appropriate place in the Swagger UI.
That’s all you have to do.
Finally, run this.
Now you can see the same comments that
is displayed for every endpoint.
Of course, we have added the XML comment
only for one endpoint.
If you want, optionally, you can add the
XML comments for remaining endpoints also.
You can briefly explain the purpose of the
particular endpoint so that the other co-developers
and users can understand the purpose of that
endpoint.
What they can input, what they can expect
as output for providing clarity on endpoints to
the users.
This is the best way.
And moreover, this API slash XML file will
be automatically regenerated by .NET every time when
you build the solution.
So you can make any kind of changes
in these comments and simply build the solution
and that’s it.
It automatically reflects in API slash XML file
and the same eventually reflects in Swagger UI
too.
Play Stop Play Play Play Play Start Start Start