Swagger

Swagger:

Swagger is a powerful yet easy-to-use suite of API developer tools for teams and individuals, enabling development across the entire API life-cycle, from design and documentation, to test and deployment. Swagger is a specification for documenting REST API. It specifies the format (URL, method, and representation) to describe REST web services. Swagger is meant to enable the service producer to update the service documentation in real time so that client and documentation systems are moving at the same pace as the server. The methods, parameters, and models description are tightly integrated into the server code, thereby maintaining the synchronization in APIs and its documentation. 

Swagger is a set of open-source tools built around the OpenAPI Specification that can help you design, build, document and consume REST APIs. The major Swagger tools include:

1. Swagger Editor: browser-based editor where you can write OpenAPI specs.
2. Swagger UI: renders OpenAPI specs as interactive API documentation.
3. Swagger Codegen: generates server stubs and client libraries from an OpenAPI spec.

Advantages:

• With the Swagger framework, the server, client and documentation team can be in synchronization simultaneously.
• As Swagger is a language-agnostic specification, with its declarative resource specification, clients can easily understand and consume services without any prior knowledge of server implementation or access to the server code.
• The Swagger UI framework allows both implementers and users to interact with the API. It gives clear insight into how the API responds to parameters and options.
• Swagger responses are in JSON and XML, with additional formats in progress.
• Swagger implementations are available for various technologies like Scala, Java, and HTML5.
• Client generators are currently available for Scala, Java, JavaScript, Ruby, PHP, and Action script 3, with more client support underway.

Why have we chosen Swagger ?

• It is simple to use, to design and model APIs according to specification-based standards (OpenAPI specification).
• It has a good interface and helps improving developer experience with interactive API documentation.
• Performs simple functional tests.
• It is stable, it’s possible to reuse code.
• It has good integration plugins with Code Editors.
• It has pro and open source tools.

POSTMAN

What is Postman?
Postman is currently one of the most popular tools used in API testing. It started in 2012 as a side project by Abhinav Asthana to simplify API workflow in testing and development. API stands for Application Programming Interface which allows software applications to communicate with each other via API calls.

Why Use Postman?
Here are some reasons we should use Postman and Newman for API testing.

1. Easily create test suites

Postman allows you create collections of integration tests to ensure your API is working as expected. Tests are run in a specific order with each test being executed after the last is finished. For each test, an HTTP request is made and assertions written in javascript are then used to verify the integrity of your code. Since the tests and test assertions are written in JavaScript, we have freedom to manipulate the received data in different ways, such as creating local variables or even creating loops to repeatably run a test.

2. Store information for running tests in different environments
You wrote your test collection and it all works perfectly. You can run it again and again against your local environment and every test passes every time. But your local environment is usually configured a little differently than a test server. Luckily, Postman allows you to store specific information about different environments and automatically insert the correct environment configuration into your test. This could be a base URL, query parameters, request headers, and even body data for an HTTP post.

3. Store data for use in other tests

Postman also allows you to store data from previous tests into global variables. These variables can be used exactly like environment variables. For example, you may have an API that requires data received from another API. You can store the response (or part of the response, since it is JavaScript) and use that as part of a request header, post body, or URL for the subsequent API calls.

4. Automation Testing: Through the use of the Collection Runner or Newman, tests can be run in multiple iterations saving time for repetitive tests.

5. Debugging: Postman console helps to check what data has been retrieved making it easy to debug tests.

6. Continuous Integration: With its ability to support continuous integration, development practices are maintained.

7. Integrates with build systems, such as Jenkins using the Newman command line tool

Postman has a command line interface called Newman. Newman makes it easy to run a collection of tests right from the command line. This easily enables running Postman tests on systems that don’t have a GUI, but it also gives us the ability to run a collection of tests written in Postman right from within most build tools. Jenkins, for example, allows you to execute commands within the build job itself, with the job either passing or failing depending on the test results.

More Details about POSTMAN use this link https://www.guru99.com/postman-tutorial.html

1. What is Postman?
2. Why Use Postman?
3. How to use Postman
4. Working with GET Requests
5. Working with POST Requests
6. How to Parameterize Requests
7. How to Create Postman Tests
8. How to Create Collections
9. How to Run Collections using Collection Runner
10. How to Run Collections using Newman

API Documentation

API Documentation:

API documentation is a technical content deliverable, containing instructions about how to effectively use and integrate with an API. It’s a concise reference manual containing all the information required to work with the API, with details about the functions, classes, return types, arguments. API Documentation has traditionally been done using regular content creation and maintenance tools and text editors.

API description formats like the OpenAPI/Swagger Specification have automated the documentation process, making it easier for teams to generate and maintain them. Example of API Documentation.

Why Document APIs?

We are in the multi-platform economy era and APIs are the glue of the digital landscape. If you want your API to be used by developers, be sure to provide them with the proper documentation to understand it. Developers are very demanding people, they want to immediately understand how to use your API, they don’t want to waste time. Have a look to the following points:

• Improves the experience for developers using our API.
• Decreases the amount of time spent on-boarding new users (internal developers or external partners). New users will start being productive earlier and will not depend on a person (already with the knowledge) who would need to spend slots of their time to explain how the API is design and how it works.
• Leads to good product maintenance and quicker updates. It helps your internal teams know the details of your resources, methods, and their associated requests and responses, making maintenance and updates quicker.
• Agreement on API specs for the endpoints, data, types, attributes and more. And this helps internal and external users to understand the API and know what it can do.
• The API contract can act as the central reference that keeps all the team members aligned on what your API’s objectives are, and how the API’s resources are exposed.
• Unblocks development on different sides (front-end / back-end / mobile development) due to dependencies on specification.
• Allows identifying bugs and issues in the API’s architecture when defining it with the team.
• Decreases the amount of time (and headaches) spent on understanding how the API works and deciphering unexpected errors when using it.

Write a good Documentation:

Your documentation must be understood even by people who are new in the API Industry.

• Authentication: be sure to document this section in detail. Describes how to use authentication schemes to consume your API.
• Terms of use: the legal agreement between the producer and the consumer. Clearly specify the constraints and help consumers to understand what are the permitted uses of your API.
• Change-log: update the versions of your API, making it stable for your consumers.
• Error messages: Error messages are also critical because they tell your consumers when they are using your API incorrectly. Provide also the solutions to overcome them. Write down all the possible error codes.