{"schemaVersion":1,"title":"Ingest an OpenAPI document","url":"https://appgram.github.io/docsy/versions/current/es/guides/tutorials/openapi-ingestion","markdownUrl":"https://appgram.github.io/docsy/format-md/versions/current/es/guides/tutorials/openapi-ingestion","jsonUrl":"https://appgram.github.io/docsy/agent/pages/versions/current/es/guides/tutorials/openapi-ingestion.json","version":"current","locale":"es","markdown":"# Ingest an OpenAPI document\n\nTurn a local or remote OpenAPI source into grouped, searchable API reference pages.\n\nWritten by: [nedimf](https://github.com/nedimf), [AppGram](https://appgram.dev)\n\nDocsy converts Swagger 2 or OpenAPI 3 documents into normalized endpoint pages, navigation targets, search entries, request examples, response examples, and Markdown exports.\n\n## Try the live portal sample\n\nOpen [Posts · requests](/api/posts) for GET, POST, PUT, PATCH, and DELETE examples, or [Comments · query parameters](/api/comments) for a filtered GET. Copy a curl command into your terminal to make the request. Docsy displays request examples; it does not execute them in the browser.\n\nThese pages use the public [JSONPlaceholder test API](https://jsonplaceholder.typicode.com/guide/). No signup or API key is needed. Writes are simulated, not persisted. Response blocks are illustrative schema examples; live GET text can differ.\n\nThe input is a **Docsy-authored OpenAPI subset**, not an official specification published by JSONPlaceholder. It is committed as `sources/samples/jsonplaceholder.openapi.yaml`, so builds do not depend on fetching a remote specification. The old Nager.Date snapshot remains in `sources/openapi.json` as an alternative source.\n\nThe portal enables the sample entirely through YAML:\n\n```yaml\ningestion:\n  openapi:\n    enabled: true\n    source: sources/samples/jsonplaceholder.openapi.yaml\n    apiBaseUrl: https://jsonplaceholder.typicode.com\n    sections:\n      - section: posts\n        title: Posts · OpenAPI sample\n        description: Public requests; writes are simulated, not persisted.\n        tags: [posts]\n      - section: comments\n        title: Comments · OpenAPI sample\n        description: Filter comments by postId.\n        tags: [comments]\n```\n\nFor example, the specification’s POST request contains:\n\n```yaml\nrequestBody:\n  required: true\n  content:\n    application/json:\n      schema:\n        $ref: '#/components/schemas/PostInput'\n      example:\n        title: Hello from Docsy\n        body: This request example comes from OpenAPI, not hardcoded UI.\n        userId: 1\n```\n\nDocsy turns that into the body fields and JSON curl payload on the Posts page. A parameter’s `example`, named `examples`, schema `example`, or schema `default` supplies the generated request value. Optional query and header parameters appear in curl when an example is available; required parameters without examples retain placeholders. Scalar parameter values are URL-encoded in paths and queries. Complex OpenAPI parameter serialization styles are not implemented.\n\n## Choose a source\n\nUse a project-relative JSON or YAML file for deterministic and private builds:\n\n```yaml\ningestion:\n  openapi:\n    enabled: true\n    source: sources/openapi.yaml\n    apiBaseUrl: https://api.example.com\n```\n\nOr fetch a public document during the build:\n\n```yaml\ningestion:\n  openapi:\n    enabled: true\n    source: https://api.example.com/openapi.json\n    apiBaseUrl: https://api.example.com\n```\n\n`source` tells Docsy where the description lives. `apiBaseUrl` is the request origin used in generated curl examples.\n\n## Choose request languages in YAML\n\nThe portal supports 24 language/client targets. These are **HTTP request snippets**, separate from importing a library's native documentation.\n\n```yaml\ningestion:\n  openapi:\n    enabled: true\n    source: sources/openapi.yaml\n    apiBaseUrl: https://api.example.com\n    examples:\n      languages: [curl, typescript, python, go, swift, kotlin, dart, csharp]\n      defaults: required\n      customSamples: true\n```\n\n`languages` controls the visible choices and their order. The selector remembers the reader's language across endpoint cards and pages. A single language hides the selector. Unknown language keys, duplicate entries, and empty lists fail YAML validation.\n\nSupported keys are `curl`, `javascript`, `typescript`, `node`, `python`, `go`, `java`, `kotlin`, `csharp`, `c`, `cpp`, `rust`, `swift`, `objectivec`, `dart`, `php`, `ruby`, `scala`, `elixir`, `lua`, `fsharp`, `visualbasic`, `powershell`, and `r`. JavaScript and TypeScript use fetch; Node is a separate runtime target, and C/C++ share a libcurl request backend. These are not 24 distinct programming languages.\n\n`defaults: required` includes required parameters plus optional parameters with explicit examples/default values. `defaults: all` also includes placeholders for other optional query/header parameters. Credentials always use placeholders. Do not put live secrets in specifications or samples.\n\nGenerated samples share one normalized method, URL, headers, and body. Their client libraries must be installed by the reader: examples include Python requests, Kotlin OkHttp, Dart http, Rust reqwest, R httr, and Lua-cURL. Other targets use their standard HTTP APIs or the library shown in the selector. Some snippets are intended to be placed inside a program rather than executed as standalone files.\n\nAll configured request samples are also exported to Markdown and agent JSON. Search indexes their text. They are displayed and copied, never executed by Docsy.\n\n## Supply actual SDK calls\n\nHTTP snippets do not magically know your SDK's method names. Put real SDK examples on an operation using `x-codeSamples`:\n\n```yaml\npaths:\n  /posts:\n    post:\n      # Keep the operation's requestBody, responses, etc.\n      x-codeSamples:\n        - lang: python\n          label: Your Python SDK\n          source: |\n            client.posts.create(title=\"Hello from Docsy\", user_id=1)\n```\n\nWith `customSamples: true` (the default), matching custom samples replace the generated example for that configured language. Other languages remain generated. With `customSamples: false`, Docsy ignores these overrides. Multiple custom examples can share a language with distinct labels. The example above illustrates the extension shape; replace it with calls from your actual SDK.\n\n## Group endpoints into pages\n\nEach entry in `sections` creates `/api/<section>`:\n\n```yaml\ningestion:\n  openapi:\n    enabled: true\n    source: sources/openapi.yaml\n    apiBaseUrl: https://api.example.com\n    guide:\n      label: Authentication guide\n      href: /guides/authentication\n    sections:\n      - section: users\n        title: Users\n        description: Create and manage users.\n        tags: [users]\n        paths: [/v1/users]\n      - section: billing\n        title: Billing\n        description: Subscriptions, invoices, and payment methods.\n        tags: [billing]\n        paths: [/v1/invoices, /v1/subscriptions]\n```\n\nMatching is case-insensitive. An operation belongs to a section when either:\n\n* One of its OpenAPI tags contains a configured `tags` value.\n* Its path contains a configured `paths` value.\n\nUse specific values when sections overlap. An operation can appear in more than one section when it matches more than one rule.\n\n## Add pages to navigation\n\nSections create routes; navigation controls discovery and order:\n\n```yaml\nnavigation:\n  - title: API Reference\n    items:\n      - title: Users\n        href: /api/users\n      - title: Billing\n        href: /api/billing\n```\n\n## Add SDK reference sources\n\nSDK adapters normalize external documentation metadata into the same rendered model:\n\n```yaml\ningestion:\n  sdks:\n    - id: javascript\n      slug: javascript-sdk\n      adapter: typedoc\n      source: sources/javascript/docs.json\n      name: JavaScript SDK\n      language: typescript\n      install: npm install @acme/sdk\n      overview: Typed client for the Acme API.\n  openapi:\n    enabled: true\n    source: sources/openapi.yaml\n    apiBaseUrl: https://api.example.com\n    sections: []\n```\n\nAvailable adapters are `typedoc`, `typedoc-lite`, `swift-symbols`, and `dartdoc`. Source paths are resolved from the project root.\n\n## Keep protected sources private\n\nCommit private or air-gapped input beneath `sources/`, or provide it during the build. Never place a protected OpenAPI or SDK source under `public/`; public assets are served without lock-mode checks.\n\nNext: [protect documentation by tier](../lock-mode).\n\n","contentLocale":"en","isFallback":true,"authorship":{"authors":[{"name":"nedimf","kind":"human","github":"nedimf","avatar":"/docsy/assets/authors/nedimf.png","role":"AppGram","id":"nedimf","url":"https://github.com/nedimf"},{"name":"AppGram","kind":"organization","github":"AppGram","url":"https://appgram.dev","avatar":"/docsy/assets/ag-logo.svg","id":"appgram"}],"contributors":[],"reviewedBy":[]},"editUrl":"https://github.com/AppGram/docsy/edit/main/content/tutorials/openapi-ingestion.md"}