How to define API interface using OpenAPI specification in FastAPI

How to use the OpenAPI specification to define API interfaces in FastAPI

Introduction:
When writing Web APIs, good API documentation is very important. It can provide clear documentation and interface definitions to help developers quickly understand and use APIs. The OpenAPI specification is a general API description language with powerful functions and ecosystem support that allows us to define and generate API documents in a standards-based way. FastAPI is a modern Python web framework that perfectly integrates the OpenAPI specification and provides powerful automated document generation and verification functions. This article will introduce how to use the OpenAPI specification to define API interfaces in FastAPI and provide corresponding code examples.

1. Install FastAPI and pydantic libraries
Before starting, we need to install FastAPI and pydantic libraries. They can be installed through the following command:

pip install fastapi
pip install uvicorn[standard]
pip install pydantic

2. Create a simple API interface
First, we create a simple API interface to demonstrate how to use the OpenAPI specification. In a file named main.py, write the following code:

from fastapi import FastAPI

app = FastAPI()

@app.get("/hello")
def hello():
    return {"message": "Hello, World!"}

This code creates a GET request interface for /hello and returns A JSON response containing the message field. Next, we need to run the application. It can be run through the following command:

uvicorn main:app --reload

3. Generate OpenAPI documentation
After running the application, you can open http://localhost:8000/docs in the browser to access the automatic Generated API documentation. This page is a document automatically generated by FastAPI based on the OpenAPI specification. You can see the details of the /hello interface, including path, request method, request parameters and response examples. Moreover, you can also test this interface in the documentation page.

4. Use parameter definition
In real applications, we usually need to use parameters to receive user input. FastAPI provides multiple ways to define parameters, including path parameters, query parameters, request body parameters and request header parameters. Below we will demonstrate how to use these parameters.

4.1 Path parameters
Path parameters are part of the URL, they are used to receive dynamic variables. We can define a path parameter through {}. In the example below, we create an interface that accepts a user ID as a path parameter.

from fastapi import FastAPI

app = FastAPI()

@app.get("/users/{user_id}")
def get_user(user_id: int):
    return {"user_id": user_id}

By running the app and then visiting http://localhost:8000/users/1 in your browser, you will get a JSON response{"user_id": 1 }.

4.2 Query parameters
Query parameters are part of the URL and are used to receive key-value pairs passed by the user. In FastAPI, query parameters can be defined through default values ​​in function parameters. In the example below, we create an interface that accepts the limit and offset query parameters.

from fastapi import FastAPI

app = FastAPI()

@app.get("/users/")
def get_users(limit: int = 10, offset: int = 0):
    return {"limit": limit, "offset": offset}

By running the application and then visiting http://localhost:8000/users/?limit=20&offset=10 in your browser, you will get a JSON response{ "limit": 20, "offset": 10}.

4.3 Request body parameters
The request body parameters are data passed through the HTTP request body and are usually used to receive larger data. In FastAPI, request body parameters can be defined through the model of the pydantic library. In the following example, we create an interface that accepts user information as a request body parameter.

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class User(BaseModel):
    name: str
    age: int

@app.post("/users/")
def create_user(user: User):
    return {"user": user}

After running the application, use a tool such as curl to send a POST request:

curl -X POST -H "Content-Type: application/json" -d '{"name":"Alice", "age": 25}' http://localhost:8000/users/

You will get a JSON response{"user": {"name ": "Alice", "age": 25}}.

4.4 Request header parameters
Request header parameters are parameters passed through HTTP request headers and are usually used to pass security verification information. In FastAPI, request header parameters can be defined using the Header() method in function parameters. In the example below, we create an interface that accepts the api_key request header parameter.

from fastapi import FastAPI, Header

app = FastAPI()

@app.get("/protected/")
def protected(api_key: str = Header(...)):
    return {"api_key": api_key}

By running the application and then visiting http://localhost:8000/protected/ in the browser and carrying the custom api_key request header, you will Get a JSON response {"api_key": <your_api_key>}</your_api_key>.

Conclusion:
This article introduces how to use the OpenAPI specification to define API interfaces in FastAPI. By using the decorators and parameter type annotations provided by FastAPI, we can easily define and verify API interfaces. Through the automatically generated OpenAPI documentation, we can quickly understand and use the API interface, and can easily collaborate and communicate with other developers. I hope this article can help you better define and use API interfaces in FastAPI.

The above is the detailed content of How to define API interface using OpenAPI specification in FastAPI. For more information, please follow other related articles on the PHP Chinese website!