> For the complete documentation index, see [llms.txt](https://www.pranaypourkar.co.in/the-programmers-guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.pranaypourkar.co.in/the-programmers-guide/api/api-specification/openapi-tbd.md). # OpenAPI ## Description OpenAPI, formerly known as **Swagger**, is an open-source specification for defining and documenting RESTful APIs. It provides a standard way to describe the structure of an API, including endpoints, request/response formats, authentication methods, error handling, and more. Originally developed by SmartBear Software, the OpenAPI Specification (OAS) has become a widely adopted industry standard supported by a large community of developers and organizations. Before we start any development, we need to have the endpoint neatly defined in specification and should have answer to below questions such as: * What should it receive as a request body, or what path parameters or query parameters are needed? * What would the response body look like? * What are the possible exceptions that would be returned? This shows that design should be first defined and ready before any kind of development. Once we have specification, the Swagger Codegen can be used to produce a server stub for the defined API, and all that remains is to implement the service logic, tests, and our API is ready for the deployment and consumed by other parties. An OpenAPI definition can be used by documentation generation tools to display the API, code generation tools to generate servers and clients in various programming languages, testing tools, and has many other use cases. ## **Latest Version** The latest version of the OpenAPI Specification is **3.1.0**, as of 2024. Refer to below page for more details. {% embed url="" %} ## OpenAPI Specification Details ## Best Practices ## Sample YAML OpenAPI Specification File ## Generating Code from an API Specification --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://www.pranaypourkar.co.in/the-programmers-guide/api/api-specification/openapi-tbd.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.