[[["容易理解","easyToUnderstand","thumb-up"],["確實解決了我的問題","solvedMyProblem","thumb-up"],["其他","otherUp","thumb-up"]],[["難以理解","hardToUnderstand","thumb-down"],["資訊或程式碼範例有誤","incorrectInformationOrSampleCode","thumb-down"],["缺少我需要的資訊/範例","missingTheInformationSamplesINeed","thumb-down"],["翻譯問題","translationIssue","thumb-down"],["其他","otherDown","thumb-down"]],["上次更新時間：2025-09-05 (世界標準時間)。"],[[["\u003cp\u003eThis content covers API design within Apigee and Apigee hybrid, focusing on using OpenAPI documents or GraphQL schemas to define API requirements.\u003c/p\u003e\n"],["\u003cp\u003eOpenAPI documents are standard, human-readable formats (JSON/YAML) for describing RESTful APIs, enabling the formal definition of elements like paths, parameters, and responses.\u003c/p\u003e\n"],["\u003cp\u003eGraphQL schemas define the data available in an API and use the Schema Definition Language to allow clients to query for exactly the data they need.\u003c/p\u003e\n"],["\u003cp\u003eOpenAPI and GraphQL documents serve as the source of truth throughout the API lifecycle, impacting API proxies and documentation when edited or deleted.\u003c/p\u003e\n"],["\u003cp\u003eApigee allows the creation of API proxies from OpenAPI documents, automatically generating paths, parameters, flows, and target endpoints, and also generates API reference documentation from snapshots of OpenAPI documents.\u003c/p\u003e\n"]]],[],null,["# API design overview\n\n*This page\napplies to **Apigee** and **Apigee hybrid**.*\n\n\n*View [Apigee Edge](https://docs.apigee.com/api-platform/get-started/what-apigee-edge) documentation.*\n\n\u003cbr /\u003e\n\nIn the Design phase, you define the requirements for your API. As an API designer, you plan the services you'd like to expose to consumers, and design APIs to access those services. You create one of the following documents to capture your API requirements:\n\n- An **OpenAPI document**\n- A **GraphQL schema**\n\nThe following sections provide more information about OpenAPI and GraphQL documents and the role they play in the lifecycle of your API.\nFor a comparison of the two API design options, see REST and GraphQL compared in this [blog post](https://cloud.google.com/blog/products/api-management/interacting-with-apis-rest-and-graphql).\n\nWhat is the OpenAPI Specification?\n----------------------------------\n\n\u003cbr /\u003e\n\n\"The OpenAPI Initiative (OAI) is focused on creating, evolving and promoting a vendor neutral API Description Format based on the Swagger Specification.\" For more information about the OpenAPI Initiative, see \u003chttps://openapis.org\u003e.\n\nAn **OpenAPI document** uses a standard format to describe a RESTful API. Written in either JSON or YAML format, an OpenAPI document is machine readable, yet also easy for humans to read and understand. The OpenAPI Specification enables formal description of elements of an API such as its base path, paths and verbs, headers, query parameters, content types, response models, and more. In addition, an OpenAPI document is commonly used to generate API documentation.\n\nHere's a fragment from an OpenAPI document that describes Apigee's simple hello world sample. For more information, view the OpenAPI Specification on\n[GitHub](https://github.com/apigee/api-platform-samples/tree/master/default-proxies/helloworld/openapi).\n**Tip:** Apigee supports **OpenAPI Specification 3.0** , though a subset of features are not yet supported. See [Apigee known issues](/apigee/docs/release/known-issues) and select **Integrated portal** in the **Filter by RELEASE** drop-down. \n\n openapi: 3.0.0\n info:\n description: OpenAPI Specification for the Apigee mock target service endpoint.\n version: 1.0.0\n title: Mock Target API\n paths:\n /:\n get:\n summary: View personalized greeting\n operationId: View a personalized greeting\n description: View a personalized greeting for the specified or guest user.\n parameters:\n - name: user\n in: query\n description: Your user name.\n required: false\n schema:\n type: string\n responses:\n \"200\":\n description: Success\n /help:\n get:\n summary: Get help\n operationId: Get help\n description: View help information about available resources in HTML format.\n responses:\n \"200\":\n description: Success\n ...\n\nMany excellent sources of information about OpenAPI Specifications exist. A good place to start is the [OpenAPI Initiative](https://openapis.org/) site, where you'll find overviews, blogs, and links to the [OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification/tree/master/versions). Refer to the Specification for detailed descriptions of the schema elements and data types.\n\nThere are a number of JSON and YAML example OpenAPI documents that you can download from the\n[OpenAPI Specification repository](https://github.com/OAI/OpenAPI-Specification/tree/master/examples).\n| **Note:** To try out a working example, see [Creating an API proxy from an OpenAPI Specification](/apigee/docs/api-platform/tutorials/create-api-proxy-openapi-spec).\n\nWhat is a GraphQL schema?\n-------------------------\n\nA **GraphQL schema** describes the data available in your API for a client to query.\n\nBenefits of using GraphQL include:\n\n- A single endpoint provides access to all fields for a given operation\n- The powerful query language, called Schema Definition Language, enables you to access exactly the data you need, preventing over-fetching or under-fetching of data\n- Processing of queries happens in parallel\n\nFor more information about GraphQL, see [graphql.org](https://graphql.org).\n\nThe following provides an example of a GraphQL schema that defines the data entry point (Query type), available write operations (Mutation type), and data types. \n\n type Query {\n Greeting: String\n students: [Student]\n }\n type Mutation {\n createStudent(firstName: String!, lastName: String!): Student!\n }\n type Subscription {\n newStudent: Student!\n }\n type Student {\n Id: ID!\n firstName: String!\n lastName: String!\n password: String!\n collegeId: String!\n }\n\nYou can query the GraphQL schema to return the exact data you need as a JSON payload.\n\nWhat happens if I modify a document?\n------------------------------------\n\nEach OpenAPI or GraphQL document serves as the source of truth throughout the API lifecycle. The same document is used at each phase in the API lifecycle, from development to publishing to monitoring.\n\nWhen you edit or delete a document, it has impact down the line:\n\n- If you edit a document, you need to manually edit the related artifacts including the API proxy and any API products that expose its resources, and regenerate the [API reference documentation](/apigee/docs/api-platform/publish/portal/publish-apis) to reflect the changes implemented in the document.\n- If you delete a document, you need to manually delete the related artifacts including the API proxy and edit any API products to delete related resources, and regenerate the [API reference documentation](/apigee/docs/api-platform/publish/portal/publish-apis) to reflect the removal of the document and its resources.\n\nWhat happens when I create an API proxy from an OpenAPI document?\n-----------------------------------------------------------------\n\nYou can create your API proxies from your OpenAPI documents. In just a few clicks, you'll have an API proxy with the paths, parameters, conditional flows, and target endpoints generated automatically. Then, you can add features such as OAuth security, rate limiting, and caching.\n\nYou can create an API proxy from an OpenAPI document using the Create Proxy Wizard, as described in [Using OpenAPI Specifications to generate proxies](/apigee/docs/api-platform/fundamentals/build-simple-api-proxy#openapi). For a hands-on experience, step through the [Creating an API proxy from an OpenAPI Specification](/apigee/docs/api-platform/tutorials/create-api-proxy-openapi-spec) tutorial.\n\nWhen you [publish your API](/apigee/docs/api-platform/publish/portal/publish-apis), you take a **snapshot** of the OpenAPI document to generate API reference documentation. That snapshot represents a specific revision of the description document."]]
