Skip to content

Commit 0ee0ee7

Browse files
author
Daniel Cesario
committedApr 1, 2017
(WIP) Adding swagger spec
This commit adds: * gitignore file for vim and mac dsstore * Updates README.md with swager editor options * first example definition for spekaers resources.
1 parent a3c5d78 commit 0ee0ee7

File tree

4 files changed

+546
-0
lines changed

4 files changed

+546
-0
lines changed
 

‎.gitignore

+16
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
##Vim rules
2+
# swap
3+
[._]*.s[a-v][a-z]
4+
[._]*.sw[a-p]
5+
[._]s[a-v][a-z]
6+
[._]sw[a-p]
7+
# session
8+
Session.vim
9+
# temporary
10+
.netrwhist
11+
*~
12+
# auto-generated tag files
13+
tags
14+
15+
##Mac DS_Store
16+
*.DS_Store

‎README.md

+4
Original file line numberDiff line numberDiff line change
@@ -2,3 +2,7 @@
22
Our cool project
33

44
we use #proejectx on barcelonapm slack
5+
6+
# Swagger spec (WIP)
7+
8+
To render/edit the Swagger spec got to the [Swagger Editor](http://editor.swagger.io/#!/)

‎spec/swagger.json

+302
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,302 @@
1+
{
2+
"swagger": "2.0",
3+
"schemes": [
4+
"http",
5+
"https"
6+
],
7+
"host": "barcelonapm.github.io",
8+
"basePath": "/",
9+
"info": {
10+
"description": "Project-X Swagger Specification",
11+
"version": "0.0.1",
12+
"title": "Barcelona PM - project-X",
13+
"termsOfService": "http://barcelona.pm.org/#bugs",
14+
"contact": {
15+
"email": "barcelona-pm@pm.org",
16+
"url": "https://www.meetup.com/barcelonapm/"
17+
},
18+
"license": {
19+
"name": "Dummy 2.0",
20+
"url": "http://barcelona.pm.org/"
21+
},
22+
"x-logo": {
23+
"url": "https://secure.meetupstatic.com/photos/event/5/b/1/2/600_456143314.jpeg"
24+
}
25+
},
26+
"externalDocs": {
27+
"description": "Our Cool Project",
28+
"url": "https://github.com/barcelonapm/project-X"
29+
},
30+
"produces": [
31+
"application/json",
32+
"application/xml"
33+
],
34+
"consumes": [
35+
"application/json",
36+
"application/xml"
37+
],
38+
"tags": [
39+
{
40+
"name": "Dates",
41+
"description": "Operations about dates"
42+
},
43+
{
44+
"name": "Enroll",
45+
"description": "Operations about Enrolling"
46+
},
47+
{
48+
"name": "Price",
49+
"description": "Operations about Price"
50+
},
51+
{
52+
"name": "Schedule",
53+
"description": "Operations about Schedule"
54+
},
55+
{
56+
"name": "Speakers",
57+
"description": "Operations about Speaker"
58+
},
59+
{
60+
"name": "Title",
61+
"description": "Operations about Talk Titles"
62+
}
63+
],
64+
"securityDefinitions": {
65+
"main_auth": {
66+
"type": "oauth2",
67+
"authorizationUrl": "http://example.com/api/oauth/dialog",
68+
"flow": "implicit",
69+
"scopes": {
70+
"read:speaker": "read speakers info",
71+
"write:speaker": "modify speakers",
72+
"create:speaker": "create speakers",
73+
"delete:speaker": "delete speakers"
74+
}
75+
},
76+
"api_key": {
77+
"type": "apiKey",
78+
"in": "header",
79+
"name": "api_key"
80+
}
81+
},
82+
"paths": {
83+
"/speakers/{speakerId}": {
84+
"parameters": [
85+
{
86+
"$ref": "#/parameters/pretty"
87+
}
88+
],
89+
"get": {
90+
"tags": [
91+
"Speakers"
92+
],
93+
"summary": "Get Speaker by Id.",
94+
"description": "Retrieve the Speaker identified by its Id Code.",
95+
"operationId": "getSpeakerById",
96+
"parameters": [
97+
{
98+
"$ref": "#/parameters/speakerId"
99+
}
100+
],
101+
"security": [
102+
{
103+
"main_auth": [
104+
"read:speaker"
105+
]
106+
},
107+
{
108+
"api_key": []
109+
}
110+
],
111+
"produces": [
112+
"application/json"
113+
],
114+
"responses": {
115+
"200": {
116+
"description": "Success",
117+
"schema": {
118+
"$ref": "#/definitions/Speaker"
119+
}
120+
},
121+
"403": {
122+
"description": "Forbidden"
123+
},
124+
"404": {
125+
"description": "Speaker not found"
126+
}
127+
}
128+
},
129+
"post": {
130+
"tags": [
131+
"Speakers"
132+
],
133+
"summary": "Create Speaker",
134+
"description": "This can only be done by the logged in user.",
135+
"operationId": "createSpeaker",
136+
"produces": [
137+
"application/json"
138+
],
139+
"parameters": [
140+
{
141+
"$ref": "#/parameters/speakerId"
142+
},
143+
{
144+
"$ref": "#/parameters/speakerBody"
145+
}
146+
],
147+
"security": [
148+
{
149+
"main_auth": [
150+
"create:speaker"
151+
]
152+
}
153+
],
154+
"responses": {
155+
"200": {
156+
"description": "OK"
157+
},
158+
"400": {
159+
"description": "Invalid Speaker supplied"
160+
},
161+
"404": {
162+
"description": "Speaker not found"
163+
}
164+
}
165+
},
166+
"put": {
167+
"tags": [
168+
"Speakers"
169+
],
170+
"summary": "Updated Speaker",
171+
"description": "This can only be done by the logged in user.",
172+
"operationId": "updateSpeaker",
173+
"produces": [
174+
"application/json"
175+
],
176+
"parameters": [
177+
{
178+
"$ref": "#/parameters/speakerId"
179+
},
180+
{
181+
"$ref": "#/parameters/speakerBody"
182+
}
183+
],
184+
"security": [
185+
{
186+
"main_auth": [
187+
"write:speaker"
188+
]
189+
}
190+
],
191+
"responses": {
192+
"200": {
193+
"description": "OK"
194+
},
195+
"400": {
196+
"description": "Invalid Speaker supplied"
197+
},
198+
"404": {
199+
"description": "Speaker not found"
200+
}
201+
}
202+
},
203+
"delete": {
204+
"tags": [
205+
"Speakers"
206+
],
207+
"summary": "Delete Speaker by Id.",
208+
"description": "Delete the Speaker identified by its Id Code.",
209+
"operationId": "deleteSpeakerById",
210+
"parameters": [
211+
{
212+
"$ref": "#/parameters/speakerId"
213+
}
214+
],
215+
"security": [
216+
{
217+
"main_auth": [
218+
"delete:speaker"
219+
]
220+
},
221+
{
222+
"api_key": []
223+
}
224+
],
225+
"produces": [
226+
"application/json"
227+
],
228+
"responses": {
229+
"200": {
230+
"description": "Success"
231+
},
232+
"403": {
233+
"description": "Forbidden"
234+
},
235+
"404": {
236+
"description": "Speaker not found"
237+
}
238+
}
239+
}
240+
}
241+
},
242+
"parameters": {
243+
"pretty": {
244+
"name": "pretty",
245+
"in": "query",
246+
"description": "Pretty print response",
247+
"type": "boolean"
248+
},
249+
"speakerId": {
250+
"name": "speakerId",
251+
"in": "path",
252+
"description": "Speaker Identifier",
253+
"required": true,
254+
"type": "integer",
255+
"format": "int64"
256+
},
257+
"speakerBody": {
258+
"name": "speakerBody",
259+
"in": "body",
260+
"description": "Body Definition for Speaker Object.",
261+
"required": true,
262+
"schema": {
263+
"$ref": "#/definitions/Speaker"
264+
}
265+
}
266+
},
267+
"definitions": {
268+
"Email": {
269+
"description": "User email address",
270+
"type": "string",
271+
"format": "email",
272+
"example": "john.smith@example.com"
273+
},
274+
"Speaker": {
275+
"type": "object",
276+
"properties": {
277+
"speakerId": {
278+
"description": "Speaker Identifier",
279+
"type": "integer",
280+
"format": "int64",
281+
"minLength": 1,
282+
"example": 1
283+
},
284+
"firstName": {
285+
"description": "User first name",
286+
"type": "string",
287+
"minLength": 1,
288+
"example": "John"
289+
},
290+
"lastName": {
291+
"description": "User last name",
292+
"type": "string",
293+
"minLength": 1,
294+
"example": "Smith"
295+
},
296+
"email": {
297+
"$ref": "#/definitions/Email"
298+
}
299+
}
300+
}
301+
}
302+
}

‎spec/swagger.yaml

+224
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,224 @@
1+
swagger: '2.0'
2+
schemes:
3+
- http
4+
- https
5+
host: barcelonapm.github.io # Replace with your hostname. You can also specify port e.g. example.com:777
6+
basePath: /
7+
info:
8+
description: Project-X Swagger Specification
9+
version: '0.0.1'
10+
# It can be any string but it is better to use semantic versioning: http://semver.org/
11+
# Warning: OpenAPI require version to be string, but without quotation YAML can recognize it as number.
12+
title: Barcelona PM - project-X
13+
termsOfService: 'http://barcelona.pm.org/#bugs'
14+
contact:
15+
email: barcelona-pm@pm.org
16+
url: 'https://www.meetup.com/barcelonapm/'
17+
license:
18+
name: Dummy 2.0
19+
url: 'http://barcelona.pm.org/'
20+
x-logo:
21+
url: 'https://secure.meetupstatic.com/photos/event/5/b/1/2/600_456143314.jpeg'
22+
externalDocs:
23+
description: Our Cool Project
24+
url: 'https://github.com/barcelonapm/project-X'
25+
produces:
26+
# List of mime types your API endpoins can return.
27+
# This is a global default. You can OVERWRITE it in each specific operation.
28+
# Remove the ones not used in your API
29+
- application/json
30+
- application/xml
31+
# you can add any mime type your API produces to the list
32+
consumes:
33+
# List of mime types your API endpoins consumes.
34+
# This is a global default. You can OVERWRITE it in each specific operation.
35+
# Remove the ones not supported by your API
36+
- application/json
37+
- application/xml
38+
# you can add any mime type your API consumes to the list
39+
40+
# A list of tags used by the specification with additional metadata.
41+
# The order of the tags can be used to reflect on their order by the parsing tools.
42+
tags:
43+
- name: Dates
44+
description: Operations about dates
45+
- name: Enroll
46+
description: Operations about Enrolling
47+
- name: Price
48+
description: Operations about Price
49+
- name: Schedule
50+
description: Operations about Schedule
51+
- name: Speakers
52+
description: Operations about Speaker
53+
- name: Title
54+
description: Operations about Talk Titles
55+
# Security scheme definitions that can be used across the specification.
56+
securityDefinitions:
57+
main_auth: # security definition name (you can name it as you want)
58+
type: oauth2 # authorization type, one of: oauth2, basic, apiKey
59+
# the following options are specific to oauth2 type
60+
authorizationUrl: 'http://example.com/api/oauth/dialog'
61+
flow: implicit
62+
scopes:
63+
'read:speaker': read speakers info
64+
'write:speaker': modify speakers
65+
'create:speaker': create speakers
66+
'delete:speaker': delete speakers
67+
api_key: # security definition name (you can name it as you want)
68+
type: apiKey
69+
# The following options are specific to apiKey type
70+
in: header # Where API key will be passed: header or query
71+
name: api_key # API key paramteer name
72+
# basic_auth: # security definition name (you can name it as you want)
73+
# type: basic
74+
75+
# Holds the relative paths to the individual endpoints. The path is appended to the
76+
# basePath in order to construct the full URL.
77+
paths:
78+
'/speakers/{speakerId}': # path parameter in curly braces
79+
# parameters list that are used with each operation for this path
80+
parameters:
81+
- $ref: '#/parameters/pretty'
82+
get:
83+
tags:
84+
- Speakers
85+
# summary is up to 120 symbold but we recommend to be shortest as possible
86+
summary: Get Speaker by Id.
87+
description: Retrieve the Speaker identified by its Id Code.
88+
# operationId should be unique across the whole specification
89+
operationId: getSpeakerById
90+
# list of parameters for the operation
91+
parameters:
92+
- $ref: '#/parameters/speakerId'
93+
# security schemas applied to this operation
94+
security:
95+
- main_auth:
96+
- 'read:speaker' # for auth2 provide list of scopes here
97+
- api_key: []
98+
# overwriting default global produces
99+
produces:
100+
- application/json
101+
responses: # list of responses
102+
'200':
103+
description: Success
104+
schema: # response schema can be specified for each response
105+
$ref: '#/definitions/Speaker'
106+
'403':
107+
description: Forbidden
108+
'404':
109+
description: Speaker not found
110+
# documentation for PUT operation for this path
111+
post:
112+
tags:
113+
- Speakers
114+
summary: Create Speaker
115+
description: This can only be done by the logged in user.
116+
operationId: createSpeaker
117+
produces:
118+
- application/json
119+
parameters:
120+
- $ref: '#/parameters/speakerId'
121+
- $ref: '#/parameters/speakerBody'
122+
security:
123+
- main_auth:
124+
- 'create:speaker'
125+
responses:
126+
'200':
127+
description: OK
128+
'400':
129+
description: Invalid Speaker supplied
130+
'404':
131+
description: Speaker not found
132+
# documentation for PUT operation for this path
133+
put:
134+
tags:
135+
- Speakers
136+
summary: Updated Speaker
137+
description: This can only be done by the logged in user.
138+
operationId: updateSpeaker
139+
produces:
140+
- application/json
141+
parameters:
142+
- $ref: '#/parameters/speakerId'
143+
- $ref: '#/parameters/speakerBody'
144+
security:
145+
- main_auth:
146+
- 'write:speaker'
147+
responses:
148+
'200':
149+
description: OK
150+
'400':
151+
description: Invalid Speaker supplied
152+
'404':
153+
description: Speaker not found
154+
delete:
155+
tags:
156+
- Speakers
157+
summary: Delete Speaker by Id.
158+
description: Delete the Speaker identified by its Id Code.
159+
operationId: deleteSpeakerById
160+
parameters:
161+
- $ref: '#/parameters/speakerId'
162+
security:
163+
- main_auth:
164+
- 'delete:speaker' # for auth2 provide list of scopes here
165+
- api_key: []
166+
produces:
167+
- application/json
168+
responses: # list of responses
169+
'200':
170+
description: Success
171+
'403':
172+
description: Forbidden
173+
'404':
174+
description: Speaker not found
175+
parameters:
176+
pretty:
177+
name: pretty
178+
in: query # place where paramter is passed: path, header, query or body, formData
179+
description: Pretty print response
180+
# type of the paramter: string, number, integer, boolean, array
181+
type: boolean
182+
speakerId:
183+
name: speakerId
184+
in: path
185+
description: Speaker Identifier
186+
required: true
187+
type: integer
188+
format: int64
189+
speakerBody:
190+
name: speakerBody
191+
in: body
192+
description: Body Definition for Speaker Object.
193+
required: true
194+
schema:
195+
$ref: '#/definitions/Speaker'
196+
# An object to hold data types that can be consumed and produced by operations.
197+
# These data types can be primitives, arrays or models.
198+
definitions:
199+
Email:
200+
description: User email address
201+
type: string
202+
format: email
203+
example: john.smith@example.com
204+
Speaker:
205+
type: object
206+
properties:
207+
speakerId:
208+
description: Speaker Identifier
209+
type: integer
210+
format: int64
211+
minLength: 1
212+
example: 1
213+
firstName:
214+
description: User first name
215+
type: string
216+
minLength: 1
217+
example: John
218+
lastName:
219+
description: User last name
220+
type: string
221+
minLength: 1
222+
example: Smith
223+
email:
224+
$ref: '#/definitions/Email'

0 commit comments

Comments
 (0)
Please sign in to comment.