API Endpoints Extraction from Swagger JSON - Documentation

Purpose of the Code

The purpose of the code provided is to extract API endpoint information from a Swagger JSON file (also known as OpenAPI specification). Swagger (or OpenAPI) is a specification for documenting RESTful APIs, which includes information about available endpoints, their methods, request parameters, responses, and other relevant details.

This code automates the process of extracting and formatting the API endpoints from the Swagger JSON into a readable format. The extracted data includes:

• Controller Name: The name of the controller handling the endpoint.
• HTTP Method: The HTTP method used (e.g., GET, POST, PUT, DELETE).
• Path: The URL path for the endpoint.
• Description: A brief description of what the endpoint does (if available).

The formatted output is then structured into a table-like format, which can be easily used in documentation or as a reference for developers working with the API.

---

How the Code Works

1. Swagger JSON File Input:

   • The program starts by asking the user to input the path to the Swagger JSON file. This file contains the API documentation in JSON format, typically generated by tools like Swagger UI or Swagger Editor.
   • Check Input Folder as sample input file.

2. Reading the Swagger JSON:

   • The code reads the Swagger JSON file using File.ReadAllText to load the file into a string.
   • The string is then deserialized into a JObject using the JsonConvert.DeserializeObject<JObject> method, which allows easy access to the structure of the JSON.

3. Extracting API Endpoints:

   • The code navigates through the Swagger JSON structure to find the paths object, which contains the actual API endpoints.
   • For each endpoint, the code checks the HTTP method (e.g., GET, POST) and retrieves the associated path and description.

4. Formatting the Output:

   • The extracted data is formatted into a table-like structure that lists the controller name, HTTP method, path, and description.
   • This data is then written to a text file (api_endpoints.txt), which can be easily copied and pasted into documentation or a README file.

5. Handling Missing Descriptions:

   • If a description is not available for an endpoint, the code will note that no description is available. This helps maintain a consistent format even when some details are missing.

---

Generated Output Example

The output generated by this code will be in the following format:

Controller: Account

1. | GET | paths['/api/Account']
2. | GET | paths['/api/Account/email']
3. | POST | paths['/api/Account/login']
4. | POST | paths['/api/Account/register']
5. | GET | paths['/api/Account/ConfirmEmail']
6. | GET | paths['/api/Account/address']
7. | PUT | paths['/api/Account/address']
8. | GET | paths['/api/Account/GetAllUsers']

Controller: Basket

1. | GET | paths['/api/Basket']
2. | POST | paths['/api/Basket']
3. | DELETE | paths['/api/Basket']

Controller: Excel

1. | POST | paths['/api/Excel/export']

Controller: Orders

1. | POST | paths['/api/Orders']
2. | GET | paths['/api/Orders']
3. | GET | paths['/api/Orders/{id}']
4. | GET | paths['/api/Orders/delivery']

Controller: Payments

1. | POST | paths['/api/Payments/{basketId}']
2. | POST | paths['/api/Payments/webHook']

Controller: Products

1. | GET | paths['/api/Products/get-products-without-pagination']
2. | GET | paths['/api/Products']
3. | GET | paths['/api/Products/{id}']
4. | GET | paths['/api/Products/brands']
5. | GET | paths['/api/Products/types']

---

Usage

1. Run the Application:

   • Compile and run the application using dotnet build and dotnet run.
   • The program will prompt the user to enter the path to the Swagger JSON file.

2. Input the Swagger JSON Path:

   • The user will need to provide the file path to the Swagger JSON file. This file can be obtained from the API documentation generated by tools like Swagger UI.

3. Output the API Endpoints:

   • The program will process the Swagger JSON file and output the formatted API endpoints to a text file. The user can then open the api_endpoints.txt file to view the extracted data.

4. Documentation:

   • The extracted API endpoints can be copied into the project documentation or README files to provide an easy reference for developers or users interacting with the API.

---

Benefits of Automating API Endpoint Extraction

1. Efficiency:

   • Manually extracting and formatting API endpoint details from a Swagger JSON file can be time-consuming. This code automates the process, saving time and effort.

2. Consistency:

   • By automating the extraction and formatting, the output is consistently structured, ensuring that all API endpoints are documented in the same way.

3. Up-to-date Documentation:

   • The code extracts the latest API endpoints from the Swagger file, ensuring that the documentation is always up-to-date with the actual API implementation.

4. Easy Integration:

   • The generated documentation can be easily integrated into the project’s README or any other documentation format, making it accessible to developers and users.

---

Future Enhancements

• Include Request and Response Models: The code could be extended to include information about the request and response models for each endpoint, providing more detailed documentation.
• Support for Authentication: The code could be enhanced to include details about authentication requirements (e.g., Bearer tokens) for each endpoint.
• Description Updates: The program could be extended to pull descriptions from additional metadata in the Swagger JSON, such as tags or operation summaries.

---

This documentation provides an overview of the functionality of the code, explaining how it extracts API endpoints from a Swagger JSON file and formats them for use in documentation. The automated approach ensures consistency, efficiency, and up-to-date information for developers working with the API.

Contributions

Contributions to this solution are welcome! If you have ideas for improvements or want to add new features, feel free to fork the repository, make your changes, and submit a pull request. Your contributions help make this solution even better for the community!

---