monsternames.open-api

OpenAPI definiton for the monsternames RESTAPI

Table of Contents

1. About The Project
   • Built With
2. Getting started
3. Local development
   • Validating OpenAPI definition
   • Running SwaggerUI
4. CI/CD Setup
5. Contributing
6. License
7. Acknowledgments

About The Project

This repo defines our OpenAPI definition for monsternames, and - via CI/CD - publishes the SwaggerUI static website for monsternames.

(back to top)

Built With

• Swagger
• OpenAPI specification 3.1.0
• Docker
• NPM

(back to top)

Getting Started

1. Read the OpenAPI specification if you haven't already
2. Make changes to the specification
3. Submit a pull request
4. Check the produced SwaggerUI artefact in the pipeline
5. Once merged to main, the deployment will happen for you :)

Local Development

The below instructions are to assist local development of the OpenAPI definition and/or SwaggerUI.

All instructions, unless otherwise stated, were only tested on MacOS.

Validating OpenAPI definition

1. Install swagger-cli from NPM:

npm install -g @apidevtools/swagger-cli

2. Validate:

swagger-cli validate open-api.yaml

Running SwaggerUI

1. Clone the swagger-ui docker image:

docker pull swaggerapi/swagger-ui

2. Run it, mounting our local open-api.yaml file:

docker run -it \
    --mount type=bind,source="$(pwd)"/open-api.yaml,target=/usr/share/nginx/html/open-api.yaml \
    -p 8080:8080 \
    -e API_URL=open-api.yaml \
    swaggerapi/swagger-ui

3. Navigate to localhost:8080 to see the swaggerUI

(back to top)

CI/CD setup

flowchart TD

    subgraph open_pull_request[Open Pull Request]
        validator[Validate Swagger]
    end

    subgraph on_merge_to_main[On merge to main]
        github_deployment[Update GitHub deployment]
        deploy_artefact[Deploy to S3]

        deploy_artefact --> github_deployment
    end

Contributing

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)

License

Copyright (c) 2023, Sudoblark Ltd

All rights reserved.

This source code is licensed under the BSD 3 clause license found in the LICENSE file in the root directory of this source tree.

(back to top)

Acknowledgments

• Monster Creatures Fantasty by luizmelo for the wonderful logo