Updated April 7, 2023
Introduction to Swagger version
We have a different version of swagger available in which OpenAi 3.0 is the latest one. Swagger is an interface that is used to show the rest of the API information and description using JSON. This helps us to create the documentation of rest api, test cases generation and code generation etc. Swagger can be divide into different cases such as documentation, API description and development. In the coming section of the tutorial, we will have a closer look at its different versions available in more detail for more better understating also how to implement this in our application to make it more interactive.
Explain each of the swagger version
As we already discussed, we have a different version of swagger available, and the latest is 3.0; this version comes up with so many improvements from the previously released version. This makes the rest api documentation and usage very easy for the developers, so any new person can access the endpoints with the available information by providing necessary information or input in the endpoint.
Version list:
1. Swagger 1.0: This is the first and the initial release of the Swagger API, and it got released on 10 august 2011.
2. Swagger 1.1: This is the second release of swagger with some improvements; it got released on 22 august 2012.
3. Swagger 1.2: At march 14, 20114, they release the formal document of swagger api.
4. Swagger 2.0: Now swagger 2.0 comes on 08 September 2014. This is also open source and licensed under Apache. They have provided improvements for node.js; they provide real-time support for swagger 2.0 with several node.js API.
Also, they have provided support for community tools that can be used with swagger 2.0. They have added @SwaggerDefinition annotation in the swagger 2.0; by the use of this, we can add definition level metadata for our swagger. It has many properties, which are described below in details;
a. schemas: Provide support for transfer API
b. info: This helps to provide the metadata about the rest of API. Which includes description, licensed, title etc.
c. produces: This property helps to produce the list of all mime-type produce by the rest apis.
d. consumes: This property helps to generate the list of all mime-type consumes by the rest apis.
e. tags: this helps to identify the list of tags. The specification is using this tag for metadata.
f. host: This property is used to override the host property.
Let’s see one sample syntax to use this annotation inside the class in our application see below;
syntax:
@SwaggerDefinition(
// inside this we can define all the property of this annotaion ..
)
public interface MyDemo {}
As you can see in the above syntax, we are trying to use this annotation from the swagger version 2.0; this annotation can be used in any class. We can seperate our api resource metadata from the general metadata we have by the use of this.
g. @extension: This annotation also comes up with the swagger 2.0 version release. By the use of this, we can add extension property. We have some tags define inside which it can be used, which are as follows see below;
- @Tag
- @Info
- @ApiOperations
Let’s have a look at its syntax how to use this n our application to define extension property for swagger; see below;
syntax:
name _here = {
@Extension annotaion can be used here to define it,..
})
}
As you can see in the above lines of syntax, we are defining the @Extension for swagger. First, we define the name for that, and inside it, we are defining the property.
h. ReaderListener: We have ReaderListener as the alternative to Swagger extension; if they do not work as expected, then we can make use of ReaderListener in Swagger 2.0. ReaderListener invokes after and before the swagger runtime. this helps to read all the extension that we have defined; after this, it will make a swagger definition. This provide us basic features which mentioned below;
- It helps in filtering out the unwanted and unnecessary information from the definition.
- Helps in improving security by adding model objects.
- It also helps in read and adding of the API definition.
5. Swagger 3.0.0: In this release, they made Open API specification. Got released on 26 July 2017.
5. Swagger 3.0.1: In this release, they made Open API specification (Patch release). Got released on 08 December 2017.
5. Swagger 3.0.2: In this release, they made Open API specification (Patch release). Got released on 06 October 2018.
5. Swagger 3.0.3: In this release, they made Open API specification (Patch release). Got released on 20 Feb 2010.
Swagger 3.0 release version provides more and more improvement, and also it named as OpenAi specification. It comes up with reusability, simplified structure, easy to write etc. The previous version had around 4 reusable components, which are now increased to number 9. Also, they have some of the new features like callback and links.
Improvements made in 3.0 version release for swagger :
a. Security definition has been enhanced in 3.0; They made some changes into security flow also the rename auth related keyword like:
- application to clientCredential
- accessCode to authorizationCode
b. Swagger 3.0 comes up with an update in parameter types. It has added and removed some parameter types in Swagger 3.0; the new parameter introduced is cookies and removed parameter named as formdata and body in swagger 3.0. when we talk about swagger 3.0, they also provide support for objects and array; we can also specify how we are going to serialize these elements.
Conclusion
By using Swagger API, we can document our rest api using JSON. Also, it is very helpful to get all the endpoints for our application at the same place with all the necessary information attached to it. Swagger also helps us to generate the test cases and code generation.
Recommended Articles
This is a guide to the Swagger version. Here we discuss the different versions of Swagger and how to implement this in our application. You may also have a look at the following articles to learn more –
