Skip to content

Commit

Permalink
upd
Browse files Browse the repository at this point in the history
  • Loading branch information
@Friskes
Friskes committed Apr 28, 2024
1 parent 7e3123c commit daa7182
Show file tree
Hide file tree
Showing 5 changed files with 59 additions and 44 deletions.
40 changes: 20 additions & 20 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Contribution Guide
# Contribution Guide 📖

> First off, thanks for taking the time to contribute! 😇
Expand All @@ -12,13 +12,12 @@ Contributions include but are not restricted to:

1. First, [fork](https://github.com/Friskes/drf-spectacular-websocket/fork) this [project](https://github.com/Friskes/drf-spectacular-websocket) to your own namespace using the fork button at the top right of the repository page.

2. Clone the upstream repository to local:
2. Clone your fork repository to local:
```bash
git clone https://github.com/YOURNAME/drf-spectacular-websocket.git
```

3. Add the fork as a new remote:
> where fork is the remote name of the fork repository.
```bash
git remote add fork https://github.com/YOURNAME/drf-spectacular-websocket.git
git fetch fork
Expand All @@ -35,7 +34,7 @@ Contributions include but are not restricted to:
venv/Scripts/activate # windows
```

2. Install dependencies
2. Install development dependencies
```bash
pip install ."[dev]" # linux
pip install .[dev] # windows
Expand All @@ -46,14 +45,16 @@ Contributions include but are not restricted to:
pre-commit install
```

> Run `pre-commit run --all-files` to run linters and formatters. This step is optional and will be executed automatically by git before you make a commit, but you may want to run it manually in order to apply fixes
4. (Optional) Run `pre-commit run --all-files` to run linters and formatters.
> This step is optional and will be executed automatically by git before you make a commit, but you may want to run it manually in order to apply fixes.
#### Now, all dependencies are installed into the Python environment you chose, which will be used for development after this point. 😎
#### Now, all dependencies are installed into the Python environment you chose, which will be used for development after this point 🎉.

## Making changes to the project

1. Don't modify code on the main branch, the main branch should always keep track of origin/main. 🧐
> To update main branch to date:
> Don't modify code on the main branch, the main branch should always keep track of origin/main 💡.
1. (Optional) To update main branch to date:
```bash
git pull origin main
# In rare cases that your local main branch diverges from the remote main:
Expand All @@ -70,21 +71,20 @@ Contributions include but are not restricted to:
- Writing and running tests
- Tests are contained within the `tests` directory, and follow the same directory structure as the `drf_spectacular_websocket` module. If you are adding a test case, it should be located within the correct submodule of `tests`. E.g., tests for `drf_spectacular_websocket/schemas/schema.py` reside in `tests/schemas/test_schema.py`.

1. Make your changes
3. Make your changes

### Run tests
> Make sure that nothing is broken after making changes and all tests are checked.
```bash
pytest
```
> The test suite is still simple and needs expansion! Please help write more test cases.
4. Make sure that nothing is broken after making changes and all tests are checked.
```bash
pytest
```
> The test suite is still simple and needs expansion! Please help write more test cases.
2. Commit your changes to git. We follow [conventional commits](https://www.conventionalcommits.org/) which are enforced using a pre-commit hook.
5. Commit your changes to git 📝. We follow [conventional commits](https://www.conventionalcommits.org/) which are enforced using a pre-commit hook.

3. Push the changes to your fork
6. Push the changes to your fork

4. Open a [pull request](https://docs.github.com/en/pull-requests). Give the pull request a descriptive title indicating what it changes. The style of the PR title should also follow [conventional commits](https://www.conventionalcommits.org/), and this is enforced using a GitHub action.
7. Open a [pull request](https://docs.github.com/en/pull-requests) 📥. *(using the `pull request` button at the top right of the repository page)*. Give the pull request a descriptive title indicating what it changes. The style of the PR title should also follow [conventional commits](https://www.conventionalcommits.org/).

5. Go to the [Release Action](https://github.com/Friskes/drf-spectacular-websocket/actions/workflows/publish-to-pypi.yml) and make sure that the workflow was successful.
8. Go to the [Release Action](https://github.com/Friskes/drf-spectacular-websocket/actions/workflows/publish-to-pypi.yml) and make sure that the workflow was successful ✅.

6. Wait until the pull request is accepted 😎.
9. Wait until the pull request is accepted by the repository owner ⏳.
61 changes: 38 additions & 23 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,28 +1,47 @@
# Extend websocket schema decorator for Django Channels

<div align="center">

| Project | | Status |
|-----------|:----|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| CI/CD | | [![Latest Release](https://github.com/Friskes/drf-spectacular-websocket/actions/workflows/publish-to-pypi.yml/badge.svg)](https://github.com/Friskes/drf-spectacular-websocket/actions/workflows/publish-to-pypi.yml) |
| Quality | | [![Coverage](https://codecov.io/github/Friskes/drf-spectacular-websocket/graph/badge.svg?token=vKez4Pycrc)](https://codecov.io/github/Friskes/drf-spectacular-websocket) |
| Package | | [![PyPI - Version](https://img.shields.io/pypi/v/drf-spectacular-websocket?labelColor=202235&color=edb641&logo=python&logoColor=edb641)](https://badge.fury.io/py/drf-spectacular-websocket) ![PyPI - Support Python Versions](https://img.shields.io/pypi/pyversions/drf-spectacular-websocket?labelColor=202235&color=edb641&logo=python&logoColor=edb641) ![Project PyPI - Downloads](https://img.shields.io/pypi/dm/drf-spectacular-websocket?logo=python&label=downloads&labelColor=202235&color=edb641&logoColor=edb641) |
| Meta | | [![types - Mypy](https://img.shields.io/badge/types-Mypy-202235.svg?logo=python&labelColor=202235&color=edb641&logoColor=edb641)](https://github.com/python/mypy) [![License - MIT](https://img.shields.io/badge/license-MIT-202235.svg?logo=python&labelColor=202235&color=edb641&logoColor=edb641)](https://spdx.org/licenses/) [![linting - Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v2.json&labelColor=202235)](https://github.com/astral-sh/ruff) [![code style - Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/format.json&labelColor=202235)](https://github.com/psf/black) |

</div>

> Provides [extend_ws_schema](#About-decorator) decorator to documentation [Cunsumer](https://channels.readthedocs.io/en/latest/topics/consumers.html) methods from [channels](https://github.com/django/channels) just like it does [drf-spectacular](https://github.com/tfranzel/drf-spectacular)

## Install
1. `pip install drf-spectacular-websocket`
2. `python manage.py collectstatic` for sidecar static
1. Install package
```bash
pip install drf-spectacular-websocket
```

2. Create sidecar static
```bash
python manage.py collectstatic
```

3. Add app name to `INSTALLED_APPS`
```python
INSTALLED_APPS = [
# drf_spectacular_websocket must be higher than drf_spectacular
'drf_spectacular_websocket',
'drf_spectacular',
'drf_spectacular_sidecar',
]
```
> `drf_spectacular_websocket` must be higher than `drf_spectacular`
```python
INSTALLED_APPS = [
'drf_spectacular_websocket',
'drf_spectacular',
'drf_spectacular_sidecar',
]
```


## Configure settings
```python
ASGI_APPLICATION = 'path.to.your.application'

# default settings (there is no need to define in your application)
# (Optional) this is default settings are automatically set by the drf_spectacular_websocket.
# You can override them in your application if necessary.
SPECTACULAR_SETTINGS = {
'DEFAULT_GENERATOR_CLASS': 'drf_spectacular_websocket.schemas.WsSchemaGenerator',
'SWAGGER_UI_DIST': 'SIDECAR',
Expand All @@ -34,27 +53,18 @@ SPECTACULAR_SETTINGS = {
'socketMessagesInitialOpened': False, # Automatically open the log window when opening swagger
},
}

# you can override this default settings in your application:
# connectSocket
# socketMaxMessages
# socketMessagesInitialOpened
```

> drf_spectacular_websocket automatically finds websocket urls and related consumer using `ASGI_APPLICATION` setting.
## About decorator
drf_spectacular_websocket `extend_ws_schema` accepts one new `type` parameter relative to drf_spectacular `extend_schema`.
- `type`
`extend_ws_schema` decorator accepts one new `type` parameter relative to drf_spectacular `extend_schema`.
- possible values:
- `send` - Type of interaction, [request -> response]
- `receive` - Type of interaction, [response without request]


## Usage example

> drf_spectacular_websocket automatically finds websocket urls and related consumer using `ASGI_APPLICATION` setting.
Direct usage

```python
from channels.generic.websocket import AsyncJsonWebsocketConsumer
from rest_framework.serializers import Serializer, CharField
Expand Down Expand Up @@ -109,6 +119,11 @@ class SomeConsumer(AsyncJsonWebsocketConsumer):
await self.send_json(message)
```

## Contributing
We would love you to contribute to `drf-spectacular-websocket`, pull requests are very welcome! Please see [CONTRIBUTING.md](https://github.com/Friskes/drf-spectacular-websocket/blob/main/CONTRIBUTING.md) for more information.

## Swagger Examples

### Send
![](https://raw.githubusercontent.com/Friskes/drf-spectacular-websocket/main/images/example_send.png)

Expand Down
Empty file added tests/schemas/__init__.py
View file
Empty file.
0 tests/expected_schemas.py → tests/schemas/expected_schema.py
View file
File renamed without changes.
2 changes: 1 addition & 1 deletion tests/test_schema.py → tests/schemas/test_schema.py
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
from src.drf_spectacular_websocket.schemas.schema import WsSchemaGenerator

from tests.expected_schemas import expected_schema_1
from tests.schemas.expected_schema import expected_schema_1


# python -m pip install .
Expand Down

0 comments on commit daa7182

Please sign in to comment.