Skip to content

Commit

Permalink
Merge pull request #3 from id/20241217-sync-upstream
Browse files Browse the repository at this point in the history
sync upstream
  • Loading branch information
id authored Dec 17, 2024
2 parents fd31096 + ee07b15 commit 058c6b5
Show file tree
Hide file tree
Showing 60 changed files with 1,739 additions and 1,718 deletions.
57 changes: 46 additions & 11 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -6,22 +6,57 @@ on:
- master
pull_request:
branches:
- master
- "*"
workflow_dispatch: {}
jobs:
ci:
name: Run checks and tests over ${{matrix.otp_vsn}} and ${{matrix.os}}
runs-on: ${{matrix.os}}
name: Run checks and tests over ${{matrix.otp_vsn}}
runs-on: ubuntu-22.04
strategy:
matrix:
otp_vsn: [21, 22, 23, 24]
os: [ubuntu-latest]
otp_vsn: ['25', '26']
rebar3_vsn: ['3.22']
steps:
- uses: actions/checkout@v2
- uses: actions/checkout@v3
- uses: erlef/setup-beam@v1
id: setup-beam
with:
otp-version: ${{matrix.otp_vsn}}
rebar3-version: '3.14'
- run: rebar3 xref
- run: rebar3 lint
- run: rebar3 dialyzer
- run: rebar3 ct
rebar3-version: ${{matrix.rebar3_vsn}}
- name: Restore _build
uses: actions/cache@v3
with:
path: |
_build
example/_build
key: "_build-cache-for\
-os-${{runner.os}}\
-otp-${{steps.setup-beam.outputs.otp-version}}\
-rebar3-${{steps.setup-beam.outputs.rebar3-version}}\
-hash-${{hashFiles('rebar.lock')}}"
- name: Restore rebar3's cache
uses: actions/cache@v3
with:
path: ~/.cache/rebar3
key: "rebar3-cache-for\
-os-${{runner.os}}\
-otp-${{steps.setup-beam.outputs.otp-version}}\
-rebar3-${{steps.setup-beam.outputs.rebar3-version}}\
-hash-${{hashFiles('rebar.lock')}}"
- name: Format check
run: rebar3 format --verify
- run: rebar3 test
- name: test our example
run: |
cd example
rebar3 release
_build/default/rel/example/bin/example daemon
_build/default/rel/example/bin/example ping
- name: Format check
run: |
cd example
rebar3 format --verify
- name: check our example
run: |
cd example
rebar3 test
52 changes: 52 additions & 0 deletions .github/workflows/up_swagger.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
#!/bin/bash

set -eux

# Get Swagger UI version and compare to imported one. Exit if same...
npm install swagger-ui-dist
rm -f package-lock.json
rm -f package.json
NEW_SWAGGER_VSN=$(jq -r .version <node_modules/swagger-ui-dist/package.json)
OLD_SWAGGER_VSN=$(cat SWAGGER_VSN)

if [[ "${NEW_SWAGGER_VSN}" = "${OLD_SWAGGER_VSN}" ]]; then
# no change
exit
fi

# Swagger UI version is different from imported one. Update...
rm -rf priv/swagger
mkdir -p priv/swagger
mv -f node_modules/swagger-ui-dist/* priv/swagger
rm -rf node_modules

# Same as https://github.com/swagger-api/swagger-ui/blob/63ad6f6a5bce19075e717ea74acaf9f7055dcdf5/docker/docker-entrypoint.d/40-swagger-ui.sh#L12
FIND="\"https://petstore.swagger.io/v2/swagger.json\""
REPLACE="window.location.origin + \"/api-docs/swagger.json\""
sed -i -e "s|${FIND}|${REPLACE}|g" priv/swagger/swagger-initializer.js

echo "${NEW_SWAGGER_VSN}" >SWAGGER_VSN

git config user.name "GitHub Actions"
git config user.email "[email protected]"

BRANCH=feature/swagger-ui-update

if git show-ref --verify --quiet "refs/heads/${BRANCH}"; then
# already exists
exit
fi

git fetch origin
git checkout -b "${BRANCH}"

if ! git diff --exit-code 1>/dev/null; then
# there's stuff to push
git add .
git commit -m "Update Swagger UI to ${NEW_SWAGGER_VSN}"
git push origin "${BRANCH}"

gh pr create --fill \
--title "Update Swagger UI to ${NEW_SWAGGER_VSN} (automation)" \
--body "This is an automated action to update the repository's Swagger UI version"
fi
18 changes: 18 additions & 0 deletions .github/workflows/up_swagger.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
---
name: Swagger UI

"on":
schedule:
- cron: '0 12 * * *'
workflow_dispatch:

jobs:
update:
name: Update
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: |
./.github/workflows/up_swagger.sh
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
21 changes: 3 additions & 18 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -1,21 +1,6 @@
_rel/
relx
*.d
.eunit
/deps
*.o
*.beam
*.plt
_*
erl_crash.dump
ebin
rel/example_project
.concrete/DEV_MODE
.rebar
.erlang.mk
log
doc/
.rebar3
logs
doc
_build
.rebar3/
example/compile_commands.json
example/_checkouts/
2 changes: 2 additions & 0 deletions .hound.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
jshint:
config_file: .jshintrc
4 changes: 4 additions & 0 deletions .jshintrc
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
{
"asi": true,
"esversion": 6
}
33 changes: 33 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,38 @@
# Changelog

## [2.5.0](https://github.com/inaka/cowboy_swagger/tree/2.5.0) (2021-09-23)

[Full Changelog](https://github.com/inaka/cowboy_swagger/compare/2.4.0...2.5.0)

**Merged pull requests:**

- support component parameters [\#140](https://github.com/inaka/cowboy_swagger/pull/140) ([zhongwencool](https://github.com/zhongwencool))

## [2.4.0](https://github.com/inaka/cowboy_swagger/tree/2.4.0) (2021-09-03)

[Full Changelog](https://github.com/inaka/cowboy_swagger/compare/2.3.0...2.4.0)

**Closed issues:**

- New swagger UI version [\#136](https://github.com/inaka/cowboy_swagger/issues/136)

**Merged pull requests:**

- Swagger UI [\#139](https://github.com/inaka/cowboy_swagger/pull/139) ([DDDHuang](https://github.com/DDDHuang))

## [2.3.0](https://github.com/inaka/cowboy_swagger/tree/2.3.0) (2021-07-28)

[Full Changelog](https://github.com/inaka/cowboy_swagger/compare/2.2.2...2.3.0)

**Closed issues:**

- Open API servers field & swagger basePath filed [\#134](https://github.com/inaka/cowboy_swagger/issues/134)

**Merged pull requests:**

- Allow for analysis under rebar3\_hank [\#137](https://github.com/inaka/cowboy_swagger/pull/137) ([paulo-ferraz-oliveira](https://github.com/paulo-ferraz-oliveira))
- basePath & servers support; support more schema type [\#135](https://github.com/inaka/cowboy_swagger/pull/135) ([DDDHuang](https://github.com/DDDHuang))

## [2.2.2](https://github.com/inaka/cowboy_swagger/tree/2.2.2) (2021-07-01)

[Full Changelog](https://github.com/inaka/cowboy_swagger/compare/2.2.1...2.2.2)
Expand Down
4 changes: 2 additions & 2 deletions LICENSE
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
https://www.apache.org/licenses/

TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION

Expand Down Expand Up @@ -192,7 +192,7 @@
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0
https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
Expand Down
40 changes: 22 additions & 18 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,38 +1,40 @@
<img src="http://www.braveterry.com/wp-content/uploads/2015/03/swagger2.png"/>
<img src="https://www.braveterry.com/wp-content/uploads/2015/03/swagger2.png"/>

# cowboy-swagger
[Swagger](http://swagger.io/) integration for [Cowboy](https://github.com/ninenines/cowboy) (built on [trails](https://github.com/inaka/cowboy-trails)).

[Swagger](https://swagger.io/) integration for [Cowboy](https://github.com/ninenines/cowboy) (built on [trails](https://github.com/inaka/cowboy-trails)).

![build](https://github.com/inaka/cowboy_swagger/workflows/build/badge.svg)

## Contact Us

If you find any **bugs** or have a **problem** while using this library, please
[open an issue](https://github.com/inaka/elvis/issues/new) in this repo
[open an issue](https://github.com/inaka/cowboy_swagger/issues/new) in this repo
(or a pull request :)).

## Requirements
Cowboy Swagger requires Erlang 18+ after 0.1.0 version

## Why Cowboy Swagger?

Simple, because there isn't a tool in Erlang to document Cowboy RESTful APIs easy and fast,
and to improve development productivity.

With `cowboy_swagger` is possible to integrate Swagger to your Erlang projects that use Cowboy as a web server.
It is extremely easy to use, and with just a few steps you'll have a nice Web documentation for your RESTful APIs.

To learn a bit more about Swagger, please check this [blog post](http://inaka.net/blog/2015/06/23/erlang-swagger-2015/).
To learn a bit more about Swagger, please check this [blog post](https://web.archive.org/web/20161110235900/https://inaka.net/blog/2015/06/23/erlang-swagger-2015/).

## How to Use it?

This is the best part. It is extremely easy.

### 1. Document each Cowboy Handler

Because `cowboy_swagger` runs on top of `trails`, the first thing that you have to do
is document all about your handler within the trails metadata. Keep in mind that
all fields defined within each method into the metadata must be compliant with the
[Swagger specification](http://swagger.io/specification).
[Swagger specification](https://swagger.io/specification).

For example, suppose that you have `example_echo_handler`, so it must implement the `trails/0`
callback from `trails_handler` behaviour:
For example, suppose that you have `example_echo_handler`, so it must implement the
`c:trails_handler:trails/0` callback:

```erlang
trails() ->
Expand All @@ -58,9 +60,10 @@ trails() ->
[trails:trail("/message/[:echo]", example_echo_handler, [], Metadata)].
```

To get a better idea of how your handler should look like, please check [here](./example/src/example_echo_handler.erl).
To get a better idea of how your handler should look like, please check [`example/src/example_echo_handler.erl`](https://github.com/inaka/cowboy_swagger/blob/master/example/src/example_echo_handler.erl).

### 2. Include cowboy_swagger in your app

First, you need to include `cowboy_swagger_handler` module in your list of trails to be compiled.

```erlang
Expand All @@ -74,7 +77,7 @@ trails:store(Trails),
Dispatch = trails:single_host_compile(Trails),
```

The snippet of code above is usually placed when you start `cowboy`. Check it [here](./example/src/example.erl#L31).
The snippet of code above is usually placed when you start `cowboy`. Check it [here](https://github.com/inaka/cowboy_swagger/blob/master/example/src/example.erl).

Then add `cowboy_swagger` to the list of apps to be loaded in your `*.app.src` file.

Expand Down Expand Up @@ -140,10 +143,10 @@ Additionally, `cowboy_swagger` can be configured/customized from a `*.config` fi

### Definitions

[Definitions](http://swagger.io/specification/#definitionsObject) can be used for describing
[parameters](http://swagger.io/specification/#parametersDefinitionsObject),
[responses](http://swagger.io/specification/#responsesDefinitionsObject) and
[security](http://swagger.io/specification/#securityDefinitionsObject) schemas.
[Definitions](https://swagger.io/specification/#definitionsObject) can be used for describing
[parameters](https://swagger.io/specification/#parametersDefinitionsObject),
[responses](https://swagger.io/specification/#responsesDefinitionsObject) and
[security](https://swagger.io/specification/#securityDefinitionsObject) schemas.

For adding definitions to your app, you have 2 choices:

Expand All @@ -155,6 +158,7 @@ Let's say you want to describe a `POST` call to a `newspapers` endpoint that req
`name` and `description` fields only, you can do it like this:

**Option 1:**

```erlang
[ ... % other configurations
, { cowboy_swagger
Expand Down Expand Up @@ -204,7 +208,6 @@ trails() ->
...
```


Now in your handler's trails callback function you can use it:

```erlang
Expand Down Expand Up @@ -241,4 +244,5 @@ model in swagger-ui, so client developers will know exactly what parameters
the API expects for every endpoint.

## Example
For more information about `cowboy_swagger` and how to use it, please check this [Example](./example).

For more information about `cowboy_swagger` and how to use it, please check this [Example](https://github.com/inaka/cowboy_swagger/tree/master/example).
1 change: 1 addition & 0 deletions SWAGGER_VSN
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
5.17.14
42 changes: 15 additions & 27 deletions elvis.config
Original file line number Diff line number Diff line change
@@ -1,27 +1,15 @@
[
{
elvis,
[
{config,
[#{dirs => ["src", "test"],
filter => "*.erl",
ruleset => erl_files
},
#{dirs => ["."],
filter => "Makefile",
rules => [{elvis_project, protocol_for_deps_erlang_mk, #{regex => "(https://.*|[0-9]+([.][0-9]+)*)"}}],
ruleset => makefiles
},
#{dirs => ["."],
filter => "rebar.config",
ruleset => rebar_config
},
#{dirs => ["."],
filter => "elvis.config",
ruleset => elvis_config
}
]
}
]
}
].
[{elvis,
[{config,
[#{dirs => ["src", "test"],
filter => "*.erl",
ruleset => erl_files,
rules =>
[{elvis_style,
atom_naming_convention,
#{regex => "^(([a-z][a-z0-9]*_?)*(_SUITE)?|basePath|swagger_2_0|openapi_3_0_0)$"}}]},
#{dirs => ["."],
filter => "rebar.config",
ruleset => rebar_config},
#{dirs => ["."],
filter => "elvis.config",
ruleset => elvis_config}]}]}].
Loading

0 comments on commit 058c6b5

Please sign in to comment.