{"id":15091169,"url":"https://github.com/refactorian/openapi-swagger-docker","last_synced_at":"2026-01-05T03:45:12.460Z","repository":{"id":247612133,"uuid":"826362668","full_name":"refactorian/openapi-swagger-docker","owner":"refactorian","description":"OpenAPI v3.x, Swagger UI v5.x, Swagger Editor v4.x, Redoc v2.x, Docker Compose, GitHub Pages","archived":false,"fork":false,"pushed_at":"2024-07-09T23:24:35.000Z","size":7121,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-27T10:29:34.597Z","etag":null,"topics":["docker","docker-compose","github-pages","githubpages","openapi","openapi-repo","openapi-spec","openapi-specification","openapi3","redoc","redocly","swagger","swagger-api","swagger-docs","swagger-ui"],"latest_commit_sha":null,"homepage":"https://refactorian.github.io/openapi-swagger-docker","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/refactorian.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-07-09T15:04:25.000Z","updated_at":"2024-07-09T23:32:30.000Z","dependencies_parsed_at":"2024-10-14T05:01:48.511Z","dependency_job_id":"3cc9da07-5226-450a-99d1-42b5675abadd","html_url":"https://github.com/refactorian/openapi-swagger-docker","commit_stats":{"total_commits":8,"total_committers":1,"mean_commits":8.0,"dds":0.0,"last_synced_commit":"96e3a48a1fc6f25d4c62581551b95407e0617099"},"previous_names":["refactorian/openapi-swagger-docker"],"tags_count":0,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/refactorian%2Fopenapi-swagger-docker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/refactorian%2Fopenapi-swagger-docker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/refactorian%2Fopenapi-swagger-docker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/refactorian%2Fopenapi-swagger-docker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/refactorian","download_url":"https://codeload.github.com/refactorian/openapi-swagger-docker/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244945596,"owners_count":20536295,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","docker-compose","github-pages","githubpages","openapi","openapi-repo","openapi-spec","openapi-specification","openapi3","redoc","redocly","swagger","swagger-api","swagger-docs","swagger-ui"],"created_at":"2024-09-25T10:36:07.632Z","updated_at":"2026-01-05T03:45:12.430Z","avatar_url":"https://github.com/refactorian.png","language":"HTML","readme":"\u003cp align=\"center\"\u003e\u003cimg src=\"https://www.openapis.org/wp-content/uploads/sites/3/2016/10/OpenAPI_Pantone.png\" width=\"500\"\u003e\u003c/p\u003e\n\n# OpenAPI, Swagger, Docker\n- OpenAPI v3.x\n- Swagger UI v5.x\n- Swagger Editor v4.x\n- Redoc v2.x\n\n# Requirements\n- Stable version of [Docker](https://docs.docker.com/engine/install/)\n- Compatible version of [Docker Compose](https://docs.docker.com/compose/install/#install-compose)\n\n# How To Deploy\n- `docker compose up -d`\n\n# Notes\n\n### Swagger UI (Docker)\n- URL: http://localhost:8080\n\n### GitHub Pages\n- Swagger UI: https://refactorian.github.io/openapi-swagger-docker\n- Swagger Editor: https://refactorian.github.io/openapi-swagger-docker/editor\n- Redoc: https://refactorian.github.io/openapi-swagger-docker/redoc\n\n### Docker compose commands\n- Build or rebuild services\n    - `docker compose build`\n- Create and start containers\n    - `docker compose up -d`\n- Stop and remove containers, networks\n    - `docker compose down`\n- Stop all services\n    - `docker compose stop`\n- Restart service containers\n    - `docker compose restart`\n- Run a command inside a container\n    - `docker compose exec [container] [command]`\n\n\n# OpenAPI Specification Guide\n\nThe OpenAPI Specification (OAS) is a standard, language-neutral way to define your API. It helps humans and computers discover and understand what your service can do, all without needing to look at the source code or documentation or inspect network traffic. An OpenAPI document is a YAML or JSON file that outlines the API’s endpoints, operations, input and output parameters, request and response formats, authentication methods, and more.\n\n### Basic Structure\n\n1. **OpenAPI Version**\n   ```yaml\n   openapi: 3.0.0\n   ```\n\n2. **Info Object**\n   ```yaml\n   info:\n     title: Sample API\n     description: API description in Markdown.\n     version: 1.0.0\n   ```\n\n3. **Servers Object**\n   ```yaml\n   servers:\n     - url: https://api.example.com/v1\n       description: Production server\n   ```\n\n4. **Paths Object**\n   ```yaml\n   paths:\n     /users:\n       get:\n         summary: Returns a list of users.\n         responses:\n           '200':\n             description: A JSON array of user names\n             content:\n               application/json:\n                 schema: \n                   type: array\n                   items:\n                     type: string\n   ```\n\n### Components\n\n1. **Schemas**\n   ```yaml\n   components:\n     schemas:\n       User:\n         type: object\n         properties:\n           id:\n             type: integer\n           name:\n             type: string\n   ```\n\n2. **Parameters**\n   ```yaml\n   components:\n     parameters:\n       UserId:\n         name: userId\n         in: path\n         required: true\n         schema:\n           type: integer\n   ```\n\n3. **Responses**\n   ```yaml\n   components:\n     responses:\n       NotFound:\n         description: Entity not found.\n   ```\n\n4. **Security Schemes**\n   ```yaml\n   components:\n     securitySchemes:\n       ApiKeyAuth:\n         type: apiKey\n         in: header\n         name: X-API-Key\n   ```\n\n### Key Elements\n\n### Paths\nDefines the available paths and operations for the API.\n```yaml\npaths:\n  /pets:\n    get:\n      summary: List all pets\n      operationId: listPets\n      responses:\n        '200':\n          description: A paged array of pets\n          content:\n            application/json:    \n              schema: \n                type: array\n                items: \n                  $ref: '#/components/schemas/Pet'\n```\n\n### Parameters\nDefines the inputs to an API method, which could be path, query, header, or cookie parameters.\n```yaml\nparameters:\n  - in: query\n    name: limit\n    schema:\n      type: integer\n    description: How many items to return at one time (max 100)\n```\n\n### Responses\nDefines the possible responses from an API method.\n```yaml\nresponses:\n  '200':\n    description: A paged array of pets\n    headers:\n      x-next:\n        description: A link to the next page of responses\n        schema:\n          type: string\n    content:\n      application/json:\n        schema: \n          type: array\n          items: \n            $ref: '#/components/schemas/Pet'\n```\n\n### Components\nHolds reusable objects, such as schemas, responses, parameters, and security definitions.\n```yaml\ncomponents:\n  schemas:\n    Pet:\n      type: object\n      required:\n        - id\n        - name\n      properties:\n        id:\n          type: integer\n          format: int64\n        name:\n          type: string\n        tag:\n          type: string\n```\n\n### Best Practices\n\n1. **Use Meaningful Descriptions:** Provide detailed descriptions for each field, endpoint, and response to make the documentation user-friendly.\n2. **Keep It DRY (Don't Repeat Yourself):** Utilize the components section to avoid redundancy.\n3. **Validate the Specification:** Use tools like Swagger or Redocly to validate and visualize your OpenAPI specification.\n4. **Document Security:** Clearly define authentication and authorization mechanisms.\n5. **Version Your API:** Include versioning in the API paths or headers to handle breaking changes gracefully.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frefactorian%2Fopenapi-swagger-docker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frefactorian%2Fopenapi-swagger-docker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frefactorian%2Fopenapi-swagger-docker/lists"}