Skip to content

Quickstart

star_openapi based on Starlette and Pydantic.

A Minimal Application⚓︎

Create hello.py:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
import uvicorn
from star_openapi import OpenAPI
from starlette.responses import PlainTextResponse

info = {"title": "Hello API", "version": "1.0.0"}
app = OpenAPI(info=info)


@app.get('/')
async def hello_world():
    return PlainTextResponse('Hello, World!')


if __name__ == '__main__':
    uvicorn.run(app)

And then run it:

1
python hello.py

You will see the output information:

1
2
3
4
INFO:     Started server process [12345]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

REST API⚓︎

You can use get, post, put, patch, delete REST API in star-openapi.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
import uvicorn
from pydantic import BaseModel
from starlette.responses import JSONResponse

from star_openapi import OpenAPI

app = OpenAPI()


class IdModel(BaseModel):
    id: int


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


@app.get("/book")
async def get_book(query: BookModel):
    return JSONResponse(query.model_dump())


@app.post("/book")
async def create_book(body: BookModel):
    return JSONResponse(body.model_dump())


@app.put("/book/{id}")
async def update_book(path: IdModel, body: BookModel):
    return JSONResponse({"id": path.id, "name": body.name, "age": body.age})


@app.delete("/book/{id}")
async def delete_book(path: IdModel):
    return JSONResponse({"id": path.id})


if __name__ == "__main__":
    print(app.routes)
    uvicorn.run(app)

APIRouter⚓︎

APIRouter allows you to organize your API endpoints into logical groups.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
import uvicorn
from starlette.responses import JSONResponse

from star_openapi import OpenAPI
from star_openapi.router import APIRouter

info = {"title": "Book API", "version": "1.0.0"}
app = OpenAPI(info=info)

api = APIRouter(url_prefix="/api")


@api.post("/book")
async def create_book():
    return JSONResponse({"message": "success"})


# register api
app.register_api(api)

if __name__ == "__main__":
    uvicorn.run(app)

Nested APIRouter⚓︎

Allow an APIRouter to be registered on another APIRouter.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
import uvicorn
from starlette.responses import JSONResponse

from star_openapi import OpenAPI
from star_openapi.router import APIRouter

info = {"title": "Book API", "version": "1.0.0"}
app = OpenAPI(info=info)

api = APIRouter(url_prefix="/api/book")
api_english = APIRouter()
api_chinese = APIRouter()


@api_english.get("/english")
async def create_english_book():
    return JSONResponse({"message": "english"})


@api_chinese.get("/chinese")
async def create_chinese_book():
    return JSONResponse({"message": "chinese"})


# register nested api
api.register_api(api_english)
api.register_api(api_chinese)
# register api
app.register_api(api)

if __name__ == "__main__":
    uvicorn.run(app)

Websocket⚓︎

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
import uvicorn
from starlette.websockets import WebSocket

from star_openapi import OpenAPI

app = OpenAPI()


@app.websocket("/ws")
async def websocket_endpoint(websocket: WebSocket):
    await websocket.accept()
    while True:
        data = await websocket.receive_text()
        await websocket.send_text(data)


if __name__ == "__main__":
    uvicorn.run("websocket:app", reload=True)