swagger open api

swagger.io/docs/specification/api-host-and-base-path/

API Server and Base Path

 

 

 

 

 

swagger.io/docs/specification/basic-structure/

Basic Structure

 

 

swagger.io/specification/

OpenAPI Specification - Version 3.0.3 | Swagger

 

 

Holds a set of reusable objects for different aspects of the OAS. All objects defined within the components object will have no effect on the API unless they are explicitly referenced from properties outside the components object.Fixed Fields

Field NameTypeDescription

schemas	Map[string, Schema Object | Reference Object]	An object to hold reusable Schema Objects.
responses	Map[string, Response Object | Reference Object]	An object to hold reusable Response Objects.
parameters	Map[string, Parameter Object | Reference Object]	An object to hold reusable Parameter Objects.
examples	Map[string, Example Object | Reference Object]	An object to hold reusable Example Objects.
requestBodies	Map[string, Request Body Object | Reference Object]	An object to hold reusable Request Body Objects.
headers	Map[string, Header Object | Reference Object]	An object to hold reusable Header Objects.
securitySchemes	Map[string, Security Scheme Object | Reference Object]	An object to hold reusable Security Scheme Objects.
links	Map[string, Link Object | Reference Object]	An object to hold reusable Link Objects.
callbacks	Map[string, Callback Object | Reference Object]	An object to hold reusable Callback Objects.

This object MAY be extended with Specification Extensions.

All the fixed fields declared above are objects that MUST use keys that match the regular expression: ^[a-zA-Z0-9\.\-_]+$.

Field Name Examples:

1. User
2. User_1
3. User_Name
4. user-name
5. my.org.User

Components Object Example

1. "components": {
2. "schemas": {
3. "GeneralError": {
4. "type": "object",
5. "properties": {
6. "code": {
7. "type": "integer",
8. "format": "int32"
9. },
10. "message": {
11. "type": "string"
12. }
13. }
14. },
15. "Category": {
16. "type": "object",
17. "properties": {
18. "id": {
19. "type": "integer",
20. "format": "int64"
21. },
22. "name": {
23. "type": "string"
24. }
25. }
26. },
27. "Tag": {
28. "type": "object",
29. "properties": {
30. "id": {
31. "type": "integer",
32. "format": "int64"
33. },
34. "name": {
35. "type": "string"
36. }
37. }
38. }
39. },
40. "parameters": {
41. "skipParam": {
42. "name": "skip",
43. "in": "query",
44. "description": "number of items to skip",
45. "required": true,
46. "schema": {
47. "type": "integer",
48. "format": "int32"
49. }
50. },
51. "limitParam": {
52. "name": "limit",
53. "in": "query",
54. "description": "max records to return",
55. "required": true,
56. "schema" : {
57. "type": "integer",
58. "format": "int32"
59. }
60. }
61. },
62. "responses": {
63. "NotFound": {
64. "description": "Entity not found."
65. },
66. "IllegalInput": {
67. "description": "Illegal input for operation."
68. },
69. "GeneralError": {
70. "description": "General Error",
71. "content": {
72. "application/json": {
73. "schema": {
74. "$ref": "#/components/schemas/GeneralError"
75. }
76. }
77. }
78. }
79. },
80. "securitySchemes": {
81. "api_key": {
82. "type": "apiKey",
83. "name": "api_key",
84. "in": "header"
85. },
86. "petstore_auth": {
87. "type": "oauth2",
88. "flows": {
89. "implicit": {
90. "authorizationUrl": "http://example.org/api/oauth/dialog",
91. "scopes": {
92. "write:pets": "modify pets in your account",
93. "read:pets": "read your pets"
94. }
95. }
96. }
97. }
98. }
99. }

1. components:
2. schemas:
3. GeneralError:
4. type: object
5. properties:
6. code:
7. type: integer
8. format: int32
9. message:
10. type: string
11. Category:
12. type: object
13. properties:
14. id:
15. type: integer
16. format: int64
17. name:
18. type: string
19. Tag:
20. type: object
21. properties:
22. id:
23. type: integer
24. format: int64
25. name:
26. type: string
27. parameters:
28. skipParam:
29. name: skip
30. in: query
31. description: number of items to skip
32. required: true
33. schema:
34. type: integer
35. format: int32
36. limitParam:
37. name: limit
38. in: query
39. description: max records to return
40. required: true
41. schema:
42. type: integer
43. format: int32
44. responses:
45. NotFound:
46. description: Entity not found.
47. IllegalInput:
48. description: Illegal input for operation.
49. GeneralError:
50. description: General Error
51. content:
52. application/json:
53. schema:
54. $ref: '#/components/schemas/GeneralError'
55. securitySchemes:
56. api_key:
57. type: apiKey
58. name: api_key
59. in: header
60. petstore_auth:
61. type: oauth2
62. flows:
63. implicit:
64. authorizationUrl: http://example.org/api/oauth/dialog
65. scopes:
66. write:pets: modify pets in your account
67. read:pets: read your pets