Example OpenAPI spec

Certainly! When you're looking for a good example API with an OpenAPI specification to test against, it's helpful to find one that is well-documented, widely used, and offers a public endpoint that you can access without requiring authentication. Here are a few notable examples:

1. Swagger Petstore

URL: https://petstore.swagger.io/

Description:
Swagger Petstore is a commonly used example API designed to demonstrate the capabilities of the OpenAPI specification. It provides a sandbox environment where you can interact with a mock pet store.

OpenAPI Specification:
The OpenAPI spec for the Swagger Petstore can be found here: https://petstore.swagger.io/v2/swagger.json

Key Features:

• Provides endpoints for CRUD operations on pets, stores, and users.
• It is publicly accessible and requires no authentication, making it perfect for testing.
• The API documentation is user-friendly and includes an interactive UI for trying out different API calls directly on the webpage.

2. JSONPlaceholder

URL: https://jsonplaceholder.typicode.com/

Description:
JSONPlaceholder is a free online REST API that you can use whenever you need some fake data. It’s useful for prototypes, testing, and learning purposes.

OpenAPI Specification:
A community-made OpenAPI spec for JSONPlaceholder isn’t always readily available directly on their site, but you can find unofficial ones on GitHub, such as this one.

Key Features:

• It offers endpoints to get data related to posts, comments, albums, photos, todos, and users.
• Highly reliable and widely used by developers for testing and prototyping.
• No authentication required.

3. OpenWeatherMap API

URL: https://openweathermap.org/api

Description:
OpenWeatherMap provides weather data, such as current weather, forecasts, and historical data. While it generally requires an API key, you can sign up for a free tier that allows you to make a limited number of requests.

OpenAPI Specification:
The OpenAPI spec can be found in their API documentation, and an example specification is available on GitHub: OpenWeatherMap OpenAPI Spec

Key Features:

• Provides access to a vast range of weather-related data.
• Suitable for testing applications that require real-time weather information.
• Free tier available, but requires sign-up for an API key.

4. GitHub API

URL: https://api.github.com/

Description:
The GitHub API provides programmatic access to all the features of GitHub, including creating repositories, managing issues and pull requests, and more.

OpenAPI Specification:
The GitHub OpenAPI definition is available at: GitHub OpenAPI Spec on GitHub

Key Features:

• Comprehensive API that covers a wide array of GitHub functionalities.
• Requires an API token for authenticated requests, but many endpoints are accessible with a personal GitHub account.
• The documentation is thorough, and the API is robust and stable.

How to Test

To test these APIs:

1. Swagger UI: Use Swagger UI if an interactive interface is available to try out API calls directly from your browser.
2. Postman: Import the OpenAPI specification into Postman to create a collection of endpoints that you can test.
3. Curl/wget: Use curl or wget from the command line to make HTTP requests.
4. Custom Code: Write custom scripts in languages like Python, JavaScript, or tools like cURL to test the API endpoints.

These examples are great starting points for exploring and testing how an OpenAPI spec works, and they help in learning more about building and consuming RESTful APIs.

I'd be happy to help!

Here is an example of a simple API that you can use to test against an OpenAPI specification:

Pet Store API

The Pet Store API is a popular example API that is often used for testing and demonstration purposes. It allows users to manage a virtual pet store, with endpoints for creating, reading, updating, and deleting pets.

OpenAPI Specification

Here is the OpenAPI specification for the Pet Store API:

openapi: 3.0.2
info:
  title: Pet Store API
  description: A simple API for managing a virtual pet store
  version: 1.0.0

paths:
  /pets:
    get:
      responses:
        200:
          description: A list of pets
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pet'
        500:
          description: Internal Server Error
      summary: Get a list of pets
      tags:
        - pets

  /pets/{petId}:
    get:
      responses:
        200:
          description: A single pet
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
        404:
          description: Pet not found
        500:
          description: Internal Server Error
      summary: Get a specific pet
      parameters:
        - in: path
          name: petId
          required: true
          schema:
            type: integer
      tags:
        - pets

  /pets:
    post:
      responses:
        201:
          description: Pet created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
        500:
          description: Internal Server Error
      summary: Create a new pet
      consumes:
        - application/json
      requestBody:
        schema:
          $ref: '#/components/schemas/Pet'
      tags:
        - pets

  /pets/{petId}:
    put:
      responses:
        200:
          description: Pet updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
        404:
          description: Pet not found
        500:
          description: Internal Server Error
      summary: Update a pet
      parameters:
        - in: path
          name: petId
          required: true
          schema:
            type: integer
      consumes:
        - application/json
      requestBody:
        schema:
          $ref: '#/components/schemas/Pet'
      tags:
        - pets

  /pets/{petId}:
    delete:
      responses:
        204:
          description: Pet deleted
        404:
          description: Pet not found
        500:
          description: Internal Server Error
      summary: Delete a pet
      parameters:
        - in: path
          name: petId
          required: true
          schema:
            type: integer
      tags:
        - pets

components:
  schemas:
    Pet:
      type: object
      properties:
        id:
          type: integer
          description: The pet's ID
        name:
          type: string
          description: The pet's name
        species:
          type: string
          description: The pet's species
      required:
        - id
        - name
        - species

securitySchemes:
  ApiKey:
    type: apiKey
    in: header
    name: Authorization

Components

The Pet Store API has the following components:

• Pet: This is an object that represents a pet. It has three properties: id, name, and species.

EndPoints

The Pet Store API has five endpoints:

1. GET /pets: Returns a list of all pets.
2. GET /pets/{petId}: Returns a specific pet by its ID.
3. POST /pets: Creates a new pet.
4. PUT /pets/{petId}: Updates a specific pet.
5. DELETE /pets/{petId}: Deletes a specific pet.

Security

The Pet Store API has a single security scheme: ApiKey. This scheme uses an API key to authenticate requests. The API key is passed in the Authorization header.

Testing

You can test the Pet Store API using a tool like Postman or cURL. Here are some examples of how you can test the API:

1. GET /pets: Send a GET request to https://api.petstore.com/pets. This should return a list of all pets.
2. GET /pets/{petId}: Send a GET request to https://api.petstore.com/pets/{petId}. Replace {petId} with the ID of the pet you want to retrieve.
3. POST /pets: Send a POST request to https://api.petstore.com/pets. Pass a JSON payload with the details of the new pet.
4. PUT /pets/{petId}: Send a PUT request to https://api.petstore.com/pets/{petId}. Pass a JSON payload with the updated details of the pet.
5. DELETE /pets/{petId}: Send a DELETE request to https://api.petstore.com/pets/{petId}. Replace {petId} with the ID of the pet you want to delete.

Remember to always test the API with a valid API key!

I hope this helps! Let me know if you have any questions or need further clarification.