{"id":26217020,"url":"https://github.com/duynghiadev/design-api","last_synced_at":"2026-04-11T20:44:45.264Z","repository":{"id":281627521,"uuid":"945868417","full_name":"duynghiadev/design-api","owner":"duynghiadev","description":"swagger, openapi","archived":false,"fork":false,"pushed_at":"2025-03-10T09:35:35.000Z","size":36,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-10T10:22:21.073Z","etag":null,"topics":["openapi","swagger-ui"],"latest_commit_sha":null,"homepage":"","language":"Go","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/duynghiadev.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":"2025-03-10T08:56:44.000Z","updated_at":"2025-03-10T09:35:39.000Z","dependencies_parsed_at":"2025-03-10T10:22:26.040Z","dependency_job_id":"3a9280be-a3f6-4f0e-a4ab-ec458c33a547","html_url":"https://github.com/duynghiadev/design-api","commit_stats":null,"previous_names":["duynghiadev/design-api"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/duynghiadev%2Fdesign-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/duynghiadev%2Fdesign-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/duynghiadev%2Fdesign-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/duynghiadev%2Fdesign-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/duynghiadev","download_url":"https://codeload.github.com/duynghiadev/design-api/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243213981,"owners_count":20254902,"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":["openapi","swagger-ui"],"created_at":"2025-03-12T12:18:35.508Z","updated_at":"2026-04-11T20:44:40.208Z","avatar_url":"https://github.com/duynghiadev.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# API Design Guide with Swagger/OpenAPI\n\n## Table of Contents\n\n- [Introduction](#introduction)\n- [What is OpenAPI/Swagger?](#what-is-openapiswagger)\n- [File Structure](#file-structure)\n- [Basic Example](#basic-example)\n- [Best Practices](#best-practices)\n\n## Introduction\n\nThis guide explains how to design and document RESTful APIs using OpenAPI (formerly known as Swagger). OpenAPI is a specification for machine-readable interface files that helps describe, produce, consume, and visualize RESTful web services.\n\n## What is OpenAPI/Swagger?\n\n- OpenAPI is the specification (current version 3.0)\n- Swagger is a set of tools for implementing the OpenAPI specification\n- Benefits:\n  - Interactive API documentation\n  - API code generation\n  - Test case generation\n  - API validation\n\n## File Structure\n\nOpenAPI documents can be written in YAML or JSON. Here's the basic structure:\n\n```yaml\nopenapi: 3.0.0\ninfo:\n  title: Sample API\n  description: Optional description\n  version: 1.0.0\nservers:\n  - url: http://api.example.com/v1\npaths:\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## Basic Example\n\nHere's a complete example of an API specification for a simple todo application:\n\n```yaml\nopenapi: 3.0.0\ninfo:\n  title: Todo API\n  description: A simple Todo API\n  version: 1.0.0\n  contact:\n    name: API Support\n    email: support@example.com\n\nservers:\n  - url: http://localhost:3000/api/v1\n    description: Development server\n\npaths:\n  /todos:\n    get:\n      summary: Get all todos\n      responses:\n        \"200\":\n          description: List of todos\n          content:\n            application/json:\n              schema:\n                type: array\n                items:\n                  $ref: \"#/components/schemas/Todo\"\n\n    post:\n      summary: Create a new todo\n      requestBody:\n        required: true\n        content:\n          application/json:\n            schema:\n              $ref: \"#/components/schemas/TodoInput\"\n      responses:\n        \"201\":\n          description: Todo created successfully\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/Todo\"\n\ncomponents:\n  schemas:\n    Todo:\n      type: object\n      properties:\n        id:\n          type: integer\n          format: int64\n        title:\n          type: string\n        completed:\n          type: boolean\n        createdAt:\n          type: string\n          format: date-time\n      required:\n        - title\n\n    TodoInput:\n      type: object\n      properties:\n        title:\n          type: string\n        completed:\n          type: boolean\n      required:\n        - title\n```\n\n## Best Practices\n\n### 1. Use Proper HTTP Methods\n\n- GET: Retrieve resources\n- POST: Create new resources\n- PUT: Update entire resources\n- PATCH: Partial updates\n- DELETE: Remove resources\n\n### 2. Schema Definitions\n\nDefine reusable components in the `components/schemas` section:\n\n```yaml\ncomponents:\n  schemas:\n    Error:\n      type: object\n      properties:\n        code:\n          type: integer\n        message:\n          type: string\n      required:\n        - code\n        - message\n```\n\n### 3. Security Definitions\n\nInclude authentication methods:\n\n```yaml\ncomponents:\n  securitySchemes:\n    bearerAuth:\n      type: http\n      scheme: bearer\n      bearerFormat: JWT\n\nsecurity:\n  - bearerAuth: []\n```\n\n### 4. Response Examples\n\nInclude examples in your documentation:\n\n```yaml\nresponses:\n  \"200\":\n    description: Successful response\n    content:\n      application/json:\n        example:\n          id: 1\n          title: \"Complete the project\"\n          completed: false\n```\n\n## Tools and Resources\n\n1. **Swagger UI**: Interactive documentation viewer\n2. **Swagger Editor**: Online editor for OpenAPI specs\n3. **Swagger Codegen**: Generate server stubs and client SDKs\n4. **Postman**: API testing and documentation\n\n## Getting Started\n\n1. Create a new file named `openapi.yaml` or `swagger.json`\n2. Define your API specification using the OpenAPI format\n3. Use Swagger UI to visualize and test your API\n4. Generate server code or documentation as needed\n\n## Validation\n\nAlways validate your OpenAPI specification using:\n\n- [Swagger Editor](https://editor.swagger.io/)\n- [OpenAPI Validator](https://github.com/swagger-api/validator-badge)\n\n## Additional Tips\n\n- Keep your API documentation up-to-date\n- Use clear and consistent naming conventions\n- Include authentication details\n- Document error responses\n- Provide examples for request/response bodies\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fduynghiadev%2Fdesign-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fduynghiadev%2Fdesign-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fduynghiadev%2Fdesign-api/lists"}