Skip to content

Commit

Permalink
Merge pull request #269 from MyParcelCOM/develop
Browse files Browse the repository at this point in the history
  • Loading branch information
yoan-myparcel authored Oct 30, 2024
2 parents caa1485 + 63d7e14 commit 7b7044d
Show file tree
Hide file tree
Showing 17 changed files with 65 additions and 76 deletions.
3 changes: 1 addition & 2 deletions .env.dist
Original file line number Diff line number Diff line change
@@ -1,3 +1,2 @@
PROJECT_NAME=myparcelcomcarrierspecification

REDOC_PORT=3300
RELEASE_VERSION=local
10 changes: 5 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
# MyParcel.com carrier API specification

[![Packagist](https://img.shields.io/packagist/v/myparcelcom/carrier-specification.svg)](https://packagist.org/packages/myparcelcom/carrier-specification)
[![OpenAPI Specification](https://img.shields.io/badge/OpenAPI-3.0-brightgreen.svg)](https://github.com/OAI/OpenAPI-Specification)
[![OpenAPI Specification](https://img.shields.io/badge/OpenAPI-3.1.0-brightgreen.svg)](https://github.com/OAI/OpenAPI-Specification)

Description of the API specification used by MyParcel.com located at [https://carrier-specification.myparcel.com](https://carrier-specification.myparcel.com). This specification adheres to the [OpenApi 3.0 specification](https://github.com/OAI/OpenAPI-Specification) and implements the [JSON API specification](https://jsonapi.org).
The microservice API specification used by MyParcel.com located at [https://carrier-specification.myparcel.com](https://carrier-specification.myparcel.com). This specification adheres to the [OpenApi 3.1.0 specification](https://github.com/OAI/OpenAPI-Specification) and implements the [JSON API specification](https://jsonapi.org).

## Content
- [Installation](#installation)
Expand All @@ -12,9 +12,9 @@ Description of the API specification used by MyParcel.com located at [https://ca
- [License](#license)

## Installation
The repository provides Docker containers to validate and preview the spec before committing changes. This is also used when validating pull requests. To install Docker, follow the steps in the [documentation](https://docs.myparcel.com/github/#docker).
The repository provides Docker containers to validate and preview the spec before committing changes. This is also used when validating pull requests. To install Docker, follow the steps in the [documentation](https://docs.myparcel.com/development.html#docker).

To setup the project for development run:
To set up the project for development run:

```bash
./mp.sh setup
Expand Down Expand Up @@ -86,4 +86,4 @@ specification/parameters/path-carrier_id.json
Unique parameters can just remain in the path file and do not need to be extracted to their own files.

## License
All software by MyParcel.com is licensed under the [MyParcel.com general terms and conditions](https://www.myparcel.com/terms).
All software by MyParcel.com is licensed under the [MyParcel.com general terms and conditions](https://www.myparcel.com/legal).
4 changes: 1 addition & 3 deletions docker-compose.yml
Original file line number Diff line number Diff line change
@@ -1,5 +1,3 @@
version: '3'

services:
bundler:
build:
Expand All @@ -14,7 +12,7 @@ services:
build:
context: .
dockerfile: docker/build/Dockerfile
image: myparcelcom/carrier-specification:v7-dev
image: myparcelcom/carrier-specification:v8-dev
volumes:
- ./dist:/usr/share/nginx/html/dist/
- ./src/index.html:/usr/share/nginx/html/index.html
Expand Down
4 changes: 2 additions & 2 deletions docker/build/Dockerfile
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
FROM node:22 as build
FROM node:22 AS build

COPY . /build
WORKDIR /build
Expand All @@ -7,7 +7,7 @@ RUN npm install -g json-refs \
&& mkdir -p dist \
&& json-refs resolve schema.json -f > dist/swagger.template.json

FROM redocly/redoc:v2.0.0
FROM redocly/redoc:v2.2.0

ENV SPEC_URL="/dist/swagger.json"
ENV PAGE_FAVICON="favicon-16x16.png"
Expand Down
7 changes: 3 additions & 4 deletions mp.sh
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,7 @@ set -o allexport
ROOT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
${ROOT_DIR}/mp/helpers/check-env
export $(cat ${ROOT_DIR}/.env | xargs)
COMPOSE="docker-compose --project-name ${PROJECT_NAME}"
RUNNING=$(${COMPOSE} ps -q)
RUNNING=$(docker compose ps -q)
}
set +o allexport

Expand All @@ -25,8 +24,8 @@ if [ $# -gt 0 ]; then
shift 1
${ROOT_DIR}/mp/${SCRIPT} "$@"
else
${COMPOSE} "$@"
docker compose "$@"
fi
else
${COMPOSE} ps
docker compose ps
fi
4 changes: 2 additions & 2 deletions mp/bundle
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
#!/usr/bin/env bash

echo -e "\033[0;30;47m Bundling spec \033[0m"
${COMPOSE} run --rm bundler bash -c "
docker compose run --rm bundler bash -c "
mkdir -p dist
json-refs resolve schema.json -f > dist/swagger.json
"
Expand All @@ -10,6 +10,6 @@ echo -e "\033[0;30;47m Injecting vars \033[0m"
# Escape "/" characters to avoid conflict with sed.
RELEASE_VERSION=${RELEASE_VERSION//\//\\/}

${COMPOSE} run --rm bundler bash -c "
docker compose run --rm bundler bash -c "
sed -i 's/\$RELEASE_VERSION/${RELEASE_VERSION}/' dist/swagger.json
"
2 changes: 1 addition & 1 deletion mp/help
Original file line number Diff line number Diff line change
Expand Up @@ -3,5 +3,5 @@
echo -e "\033[0;30;47m Available commands \033[0m"
ls -p ${ROOT_DIR}/mp | grep -v '/'

echo -e "\033[0;30;47m Available docker-compose commands \033[0m"
echo -e "\033[0;30;47m Available docker compose commands \033[0m"
echo "https://docs.docker.com/compose/reference"
2 changes: 1 addition & 1 deletion mp/up
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

echo -e "\033[0;30;47m Starting containers \033[0m"

${COMPOSE} up -d carrier-specification
docker compose up -d carrier-specification
./mp.sh bundle

echo -e "\033[0;30;47m Redoc running on \033[0m https://carrier-specification.localhost.private"
2 changes: 1 addition & 1 deletion schema.json
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
{
"openapi": "3.0.0",
"openapi": "3.1.0",
"info": {
"$ref": "./specification/info.json"
},
Expand Down
3 changes: 3 additions & 0 deletions specification/parameters.json
Original file line number Diff line number Diff line change
@@ -1,4 +1,7 @@
{
"path-collection_id": {
"$ref": "./parameters/path-collection_id.json"
},
"path-country_code": {
"$ref": "./parameters/path-country_code.json"
},
Expand Down
9 changes: 9 additions & 0 deletions specification/parameters/path-collection_id.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
{
"name": "collection_id",
"in": "path",
"description": "Identifier which has been returned in the collection POST request.",
"required": true,
"schema": {
"type": "string"
}
}
2 changes: 1 addition & 1 deletion specification/parameters/path-shipment_id.json
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,6 @@
"description": "Identifier which has been returned in the shipment POST request.",
"required": true,
"schema": {
"$ref": "#/components/schemas/Uuid"
"type": "string"
}
}
27 changes: 5 additions & 22 deletions specification/paths/Collections-collection_id.json
Original file line number Diff line number Diff line change
@@ -1,21 +1,15 @@
{
"parameters": [
{
"$ref": "#/components/parameters/path-collection_id"
}
],
"patch": {
"tags": [
"Collections"
],
"summary": "Update a collection.",
"description": "This endpoint is used to update collections.",
"parameters": [
{
"name": "collection_id",
"in": "path",
"description": "ID of the collection to be updated. Can differ from the `myparcelcom_collection_id` attribute!",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"description": "The collection object to be updated.",
"required": true,
Expand Down Expand Up @@ -139,17 +133,6 @@
],
"summary": "Void a collection.",
"description": "This endpoint is used to void collections. Not all carriers support voiding of registered shipments.",
"parameters": [
{
"name": "collection_id",
"in": "path",
"description": "ID of the collection to be voided. Can differ from the `myparcelcom_collection_id` attribute!",
"required": true,
"schema": {
"$ref": "#/components/schemas/Uuid"
}
}
],
"responses": {
"204": {
"description": "The collection has been voided."
Expand Down
4 changes: 3 additions & 1 deletion specification/schemas/Collection.json
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,9 @@
"properties": {
"myparcelcom_collection_id": {
"type": "string",
"example": "6e287731-c391-4548-bc48-c09327e1e94f"
"format": "uuid",
"example": "6e287731-c391-4548-bc48-c09327e1e94f",
"description": "Collection identifier used by MyParcel.com."
},
"name": {
"deprecated": true,
Expand Down
27 changes: 7 additions & 20 deletions specification/tags.json
Original file line number Diff line number Diff line change
@@ -1,36 +1,23 @@
[
{
"name": "Collections",
"description": ""
"name": "Collections"
},
{
"name": "Manifests",
"externalDocs": {
}
"name": "Manifests"
},
{
"name": "MultiColliShipments",
"externalDocs": {
}
"name": "MultiColliShipments"
},
{
"name": "PickupDropoffLocations",
"externalDocs": {
}
"name": "PickupDropoffLocations"
},
{
"name": "ServiceRates",
"externalDocs": {
}
"name": "ServiceRates"
},
{
"name": "Shipments",
"externalDocs": {
}
"name": "Shipments"
},
{
"name": "ValidateCredentials",
"externalDocs": {
}
"name": "ValidateCredentials"
}
]
21 changes: 15 additions & 6 deletions src/myparcelcom.css
Original file line number Diff line number Diff line change
Expand Up @@ -7,19 +7,28 @@ img[alt=logo] {
width: 200px;
}

/* Less visual emphasis on authorizations */
#redoc div > div > span > span:after {
color: rgb(8, 12, 12);
font-weight: normal;
text-transform: lowercase;
/* More visual emphasis on authorizations */
#redoc div > div > span > span > i {
color: rgb(14, 124, 134);
}

/* Less visual emphasis on length limitations */
#redoc div > div > span > span {
#redoc table div > div > span > span {
background: initial;
border: initial;
font-family: inherit;
margin: 0;
padding: 0;
color: rgb(14, 124, 134);
}

/* Less visual emphasis on response buttons */
#redoc .api-content > div > div > div:first-child > div > div > button > div {
display: inline-block;
}
#redoc .api-content > div > div > div:first-child > div > div > button > div p {
margin: 0;
}
#redoc .api-content > div > div > div:first-child > div > div > button > strong {
margin: 0 4px;
}
10 changes: 5 additions & 5 deletions src/myparcelcom.js
Original file line number Diff line number Diff line change
Expand Up @@ -68,10 +68,10 @@
function () {
requestAnimationFrame(function () {
// Open external links in a new tab.
var links = document.querySelectorAll('.api-content a')
const links = document.querySelectorAll('.api-content a')

for (var l = 0; l < links.length; l++) {
if (links[l].href.substr(0, 4) === 'http' && links[l].hostname !== window.location.hostname) {
for (let l = 0; l < links.length; l++) {
if (links[l].href.substring(0, 4) === 'http' && links[l].hostname !== window.location.hostname) {
links[l].target = '_blank'
}
}
Expand All @@ -86,15 +86,15 @@
// 4. Find the "attributes" property
if (element.innerText.includes('"attributes"')) {
// 5. Find the preceding "id" property
var id = element.parentNode.parentNode.previousSibling
const id = element.parentNode.parentNode.previousSibling
if (id.innerText.includes('"id"')) {
// 6. Hide it, this filter makes sure we do not hide "id" properties of RPC endpoints or relationships
id.style.display = 'none'
}
}
})
// 7. Hide the copy button, because this still copies a POST example including the "id".
var copyButton = element.nextSibling.querySelector('button')
const copyButton = element.nextSibling.querySelector('button')
if (copyButton) {
copyButton.style.display = 'none'
}
Expand Down

0 comments on commit 7b7044d

Please sign in to comment.