The document discusses common questions about API descriptions and OpenAPI specifications. It provides answers and examples for questions such as whether to design APIs first or code first, what tools support OpenAPI v3.0, why there are no visual editors, how to create documentation and mocks, and how to keep code and documentation in sync. It also discusses using API descriptions for validation by reusing the specifications in middleware, avoiding multiple sources of truth, and enabling validation at the client-side using JSON Schema.

1. API Descriptions as
Production Code

5. 2017-2018 QUESTIONS2017-2018 QUESTIONS
1. Design First or Code First?

6. 2017-2018 QUESTIONS2017-2018 QUESTIONS
1. Design First or Code First?
2. What tooling supports OpenAPI v3.0?

7. 2017-2018 QUESTIONS2017-2018 QUESTIONS
1. Design First or Code First?
2. What tooling supports OpenAPI v3.0?
3. Why are there no visual editors?

8. 2017-2018 QUESTIONS2017-2018 QUESTIONS
1. Design First or Code First?
2. What tooling supports OpenAPI v3.0?
3. Why are there no visual editors?
4. How/when do we create documentation?

9. 2017-2018 QUESTIONS2017-2018 QUESTIONS
1. Design First or Code First?
2. What tooling supports OpenAPI v3.0?
3. Why are there no visual editors?
4. How/when do we create documentation?
5. How/when do we create mocks?

10. 2017-2018 QUESTIONS2017-2018 QUESTIONS
1. Design First or Code First?
2. What tooling supports OpenAPI v3.0?
3. Why are there no visual editors?
4. How/when do we create documentation?
5. How/when do we create mocks?
6. How do we keep code and docs in sync?

11. What tooling supports OpenAPI v3.0?

12. What tooling supports OpenAPI v3.0?
most of it

13. What tooling supports OpenAPI v3.0?
most of it
https://openapi.tools

15. Design First or Code First?

16. class UserController {
@OpenApi(
path = "/users",
method = HttpMethod.POST,
// ...
)
public static void createUser(Context ctx) {
// ...
}
}

17. /**
* @OAGet(path="/2.0/users/{username}",
* operationId="getUserByName",
* @OAParameter(name="username",
* in="path",
* required=true,
* description=Explaining all about the username parameter
* @OASchema(type="string")
* ),
* @OAResponse(response="200",
* description="The User",
* @OAJsonContent(ref="#/components/schemas/user"),
* @OALink(link="userRepositories", ref="#/components/links
* )
* )
*/

18. Vinai Kopp, A talk at #MM18IT
Code comments are just facts waiting to
become lies.

27. Sebastien Armand, "Making OpenAPI Bearable With Your Own DSL"
While OpenAPI is great for describing
APIs, ... it's de nitely not a great
experience to write OpenAPI documents
from scratch.

28. Why are there no visual editors?

30. https://stoplight.io/studio

35. How/when do we create mocks?

36. How/when do we create mocks?
http://stoplight.io/prism

37. How/when do we create mocks?
Studio has Prism built in 🙌
http://stoplight.io/prism

38. How/when do we create mocks?
Studio has Prism built in 🙌
Hosted Prism coming soon... ⏳
http://stoplight.io/prism

39. How/when do we create documentation?

40. How/when do we create documentation?
https://stoplight.io/docs

42. ⛔How do we keep code and API docs in sync?

44. ⛔Documentation ✅API Descriptions

45. ✅How to re-use API descriptions as code!

46. Code Generation is another talk...

48. SERVER-SIDE VALIDATIONSERVER-SIDE VALIDATION
Model?

49. SERVER-SIDE VALIDATIONSERVER-SIDE VALIDATION
Model?
Controller?

50. SERVER-SIDE VALIDATIONSERVER-SIDE VALIDATION
Model?
Controller?
View? 😱

51. SERVER-SIDE VALIDATIONSERVER-SIDE VALIDATION
Model?
Controller?
View? 😱
Service?

52. SERVER-SIDE VALIDATIONSERVER-SIDE VALIDATION
Model?
Controller?
View? 😱
Service?
Contract?

53. SERVER-SIDE RUBY VALIDATIONSERVER-SIDE RUBY VALIDATION
class NewUserContract < Dry::Validation::Contract
params do
required(:email).filled(:string)
required(:age).value(:integer)
end
rule(:email) do
unless /A[w+-.]+@[a-zd-]+(.[a-zd-]+)*.[a-z]+z/i.mat
key.failure('has invalid format')
end
end
rule(:age) do
key.failure('must be greater than 18') if value < 18
end
end

54. SERVER-SIDE JAVASCRIPT VALIDATIONSERVER-SIDE JAVASCRIPT VALIDATION
import Joi from 'joi';
export default {
createUser: {
body: {
username: Joi.string().regex(/^[0-9a-fA-F]{24}$/).required(
email: Joi.string().required(),
age: Joi.number()
}
}
};

55. LOOKS LIKE AN API DESCRIPTIONLOOKS LIKE AN API DESCRIPTION
type: object
properties:
username:
type: string
email:
type: string
format: email
age:
type: integer
minimum: 18
required:
- email
- age

56. Multiple Sources Of Truth = Checking For LIES

57. Dredd, takes a lot of work and breaks so much teams
just turn it off
https://dredd.org/

58. REUSE API DESCRIPTIONS FOR VALIDATIONREUSE API DESCRIPTIONS FOR VALIDATION
No need to write any code
# config/application.rb
config.middleware.use Committee::Middleware::RequestValidation,
schema_path: 'openapi.yaml'

59. Ruby:
PHP:
NodeJS: or
Java/Kotlin:
Python:
Mojolicious:
committee
league/openapi-psr7-validator
fastify express-ajv-swagger-validation
openapi-spring-web ux-validator
connexion
Mojolicious

60. {
"errors": [
{
"status": "422",
"detail": "The property '#/widget/price' of type string
did not match the following type: integer",
"source": {
"pointer": "#/widget/price"
}
}
]
}

62. If you have validation code, you can delete it.
If this is a new application, you don't need to write it.

63. "Data-store Validations" like "is email unique" still need
to happen 👍

64. Your test suite uses descriptions to acceptance test
requests.

65. Your test suite uses descriptions to contract test
responses.

66. JsonMatchers.schema_root = "reference/example-api/models"
it 'should conform to user schema' do
get "/users/#{subject.id}"
expect(response).to match_json_schema('user')
end
https://apisyouwonthate.com/blog/writing-documentation-via-contract-testing

67. REQUEST VALIDATION AT GATEWAYREQUEST VALIDATION AT GATEWAY
Can't nd a middleware?
Middleware a bit slow in prod?

68. Gateways validate your payloads before your
application server is called

70. AWS Gateway
Azure Gateway
Kong
Tyk
Express Gateway

71. Register a middleware in dev?
Register a gateway plugin in prod?
Standards compliance should mean dev/prod parity.*

72. Another (third) source of truth for validation... the client!

76. JSON Schema at runtime
Link: <http://example.com/schemas/user.json#>; rel="describedby"

77. const ajv = new Ajv();
const userSchema = require('./cached-schema.json')
function validate(schema, data) {
return ajv.validate(schema, data)
? true : ajv.errors;
}
const input = {
name: "Lucrezia Nethersole",
email: "l.nethersole@hotmail.com",
age: 25
}
validate(userSchema, input); // true

78. validate(userSchema, { ...input, email: 123 );
[
{
keyword: 'type',
dataPath: '.email',
schemaPath: '#/properties/email/type',
params: { type: 'string' },
message: 'should be string'
}
]

79. [ 'Name is a required field' ]
[ 'Email should match format “email”' ]
[ 'Date Of Birth is in an invalid format, e.g: 1990–12–28' ]
[ 'Name should NOT be longer than 20 characters' ]

82. stoplight.io phil.tech/speaking @philsturgeon
THANK YOU!THANK YOU!
ApisYouWontHate.com
Stoplight.io