In the Swagger specification, operationIds are optional, but if specified, must be unique.įor SDK generation, operationIds are used as the name of the method corresponding to the operation, so it is important to include these in the OpenAPI definition file. OperationIdĮvery operation should have a unique operationId. When both a summary and description are provided, the description should include additional detailĪbout the operation behavior – it should not simply restate the summary. Summary and descriptionĮach operation should have a summary and/or description. Typically this order should match the order of operations in the API Reference. Operations Order of operationsĭefine basic/common operations before advanced/rare operations. Similarly, allOf will ensure that the resulting Dog and Hamster objects contain the properties derived from Pet.
Using discriminator allows for the Pet class to show up as a parent property for both Dog and Hamster in the SDK generator. The subclasses should use the allOf property to reference the superclass and define any additional properties. The discriminator should be specified on the superclass, although the value doesn’t actually affect the relationship. The discriminator field of a model can be used to create a polymorphic relationship between models. This means that a property defined with a $ref cannot be given an alternate description (or any other attribute).
Add new optional properties to the end of the property list.īe aware that the JSON Schema specification (an underlying element of the swagger/OpenAPI spec) does not allow “sibling” elements to a $ref. List all required properties before any optional properties. Models that represent body parameters may be absorbed into the parameter list for the method for the request, so additional care is needed in defining these model: Order of properties in body parameter models Typically important or fundamental properties should be listed first and ancillary properties appearing last.įor example, if a model has an “id” property that uniquely identifies an instance of the model, that should generally appear earlier in the list of properties.Īs a corollary, required properties should generally appear before optional properties in the model definition. The properties in a model definition should appear in the same order they should appear in the SDK. Mark a property as “required” if and only if it will be present and not null for every instance of the model. See Alternate names for properties or parameters belowįor a way to deal with existing properties whose names are reserved words. Avoid reserved wordsĪvoid using reserved words for model/property names (for example, error, return, type, input). The standard tools do not warn about this because the swagger spec does not restrict the values for “type” or “format”. Not defined for type number, so the actual type is a floating point (generic number). In the “Bad” example, matching_results may appear to be defined as an integer, but the integer format is Only use combinations of type and format defined in the Model properties and parameters should have well-defined type and format information. “JSON object containing request parameters.”. “An object containing request parameters.”. Rather, use the generic “object” in model descriptions. These descriptions should match the API Reference descriptions wherever practical.Īvoid describing a model as a “JSON object” since this will be incorrect for some SDKs. It is usually preferable to combine these two models by adding the two additional properties from “FooPlus” into “Foo”Įvery model and property should have a description. Use a single model to describe similar, compatible objects when practical.įor example, if a “Foo” has 8 properties and a “FooPlus” has the same 8 properties as “Foo” but also two more, Model names should be in “upper camel case”. Model names should be simple, descriptive, and meaningful to developers. Suitable for distribution in a Software Development Kit (SDK).
To address aspects of API specification related to the generation of client libraries The guidelines in this document extend and/or clarify the Swagger spec and API guidelines In addition, Watson APIs should adhere to the Watson Developer Cloud REST API guidelines: Of course, all Swagger API documents should conform to the Swagger/OpenAPI specification:
The following are guidelines for writing API descriptions using Swagger.
Excluding SDK support for some response types. Alternate names for properties or parameters. Conventions / Annotations for SDK generation. Do not explicitly define a accept-type header parameter. Do not explicitly define a content-type header parameter. Specify common parameters for a path in the path definition. Order of properties in body parameter models. Api-guidelines Swagger Coding Style Guidelines Table of Contents
0 kommentar(er)
