Aiming at 30 minutes, adding annotationbashing

Author: Phil Sturgeon

content/api-descriptions-as-production-code/img/Screen Shot 2019-09-02 at 18.29.03.png

@@ -30,14 +30,25 @@
       <div class="slides">{{{slides}}}</div>
       <div id="crashy-footer" class="footer">
         <span class="element">stoplight.io</span>
+        <span class="element">phil.tech/speaking</span>
         <span class="element">@philsturgeon</span>
-        <span class="element">#ApiCityConf</span>
       </div>
     </div>
 
     <script src="{{{base}}}/js/reveal.js"></script>
 
     <style>
+      .slides {
+        height:100%;
+        width:100%;  
+      }
+
+      .caption {
+        bottom:0px;
+        right:0px;
+        position:absolute;
+      }
+
       .footer {
         position: absolute;
         display: table;

content/api-descriptions-as-production-code/img/code-comments.jpg

@@ -0,0 +1 @@
+reveal-md source.md --template=layout.html -w

content/api-descriptions-as-production-code/img/docs.png

@@ -20,7 +20,7 @@ revealOptions:
 
 ---
 
-🌍 offset.earth 🌏
+<!-- .slide: data-background="img/offset-earth.png" -->
 
 ---
 
@@ -35,6 +35,7 @@ revealOptions:
 1. Why are there no editors? <!-- .element: class="fragment" -->
 1. How/when do we create documentation? <!-- .element: class="fragment" -->
 1. How/when do we create mocks?  <!-- .element: class="fragment" -->
+1. How can we enforce style guides for docs?  <!-- .element: class="fragment" -->
 1. How do we keep code and docs in sync?  <!-- .element: class="fragment" -->
 
 ---
@@ -43,13 +44,11 @@ revealOptions:
 
 ---
 
-<img src="img/logo.dark.png" style="border:0; background:transparent;box-shadow:0">
+<!-- .slide: data-background="img/workflow2.jpeg" data-background-size="contain" data-background-color="#fff" -->
 
 ---
 
-**Design First or Code First?**
-
-Design First <!-- .element: class="fragment" -->
+<img src="img/logo.dark.png" style="border:0; background:transparent;box-shadow:0">
 
 ---
 
@@ -61,6 +60,85 @@ https://openapi.tools <!-- .element: class="fragment" -->
 
 ---
 
+<!-- .slide: data-background="img/tools.png" data-background-size="contain" -->
+
+---
+
+**Design First or Code First?**
+
+---
+
+```java
+class UserController {
+  @OpenApi(
+      path = "/users",
+      method = HttpMethod.POST,
+      // ...
+  )
+  public static void createUser(Context ctx) {
+      // ...
+  }
+}
+```
+
+---
+
+```php
+/**
+  * @OA\Get(path="/2.0/users/{username}",
+  *   operationId="getUserByName",
+  *   @OA\Parameter(name="username",
+  *     in="path",
+  *     required=true,
+  *     description=Explaining all about the username parameter
+  *     @OA\Schema(type="string")
+  *   ),
+  *   @OA\Response(response="200",
+  *     description="The User",
+  *     @OA\JsonContent(ref="#/components/schemas/user"),
+  *     @OA\Link(link="userRepositories", ref="#/components/links/UserRepositories")
+  *   )
+  * )
+  */
+public function getUserByName($username, $newparam)
+{
+}
+```
+
+---
+
+> Code comments are just facts waiting to become lies.
+
+_<small>Vinai Kopp, A talk at #MM18IT</small>_
+
+---
+
+<!-- .slide: data-background="img/code-comments.jpg" data-background-size="contain" -->
+
+---
+
+<!-- .slide: data-background="img/wf-1.png" data-background-size="contain" data-background-color="#eee" -->
+
+---
+
+<!-- .slide: data-background="img/wf-2.png" data-background-size="contain" data-background-color="#eee" -->
+
+---
+
+<!-- .slide: data-background="img/wf-3.png" data-background-size="contain" data-background-color="#eee" -->
+
+---
+
+<!-- .slide: data-background="img/lifecycle.png" data-background-size="contain" data-background-color="#eee" -->
+
+---
+
+> While OpenAPI is great for describing APIs, ... **it's definitely not a great experience to write OpenAPI documents from scratch**.
+
+_<small>Sebastien Armand, "Making OpenAPI Bearable With Your Own DSL"</small>_
+
+---
+
 **Why are there no editors?**
 
 https://stoplight.io/studio <!-- .element: class="fragment" -->
@@ -69,18 +147,28 @@ https://stoplight.io/studio <!-- .element: class="fragment" -->
 
 <!-- .slide: data-background="img/studio.png" data-background-size="contain" data-background-color="#000" -->
 
+<!-- TODO Add file system image -->
+
 ---
 
 <!-- .slide: data-background="img/studio-adv.png" data-background-size="contain" data-background-color="#000" -->
 
 ---
 
+<!-- .slide: data-background="img/studio-md.png" data-background-size="contain" data-background-color="#fff" -->
+
+---
+
 **How/when do we create documentation?**
 
 https://stoplight.io/docs <!-- .element: class="fragment" -->
 
 ---
 
+<!-- .slide: data-background="img/docs.png" data-background-size="contain" data-background-color="#fff" -->
+
+---
+
 **How/when do we create mocks?**
 
 Studio has a mock server built right in 🙌 <!-- .element: class="fragment" -->
@@ -209,7 +297,7 @@ config.middleware.use Committee::Middleware::RequestValidation,
 
 - **Ruby:** [committee](https://github.com/interagent/committee)
 - **PHP:** [openapi-psr7-validator](https://github.com/lezhnev74/openapi-psr7-validator)
-- **NodeJS:** [fastify](https://github.com/fastify/fastify/blob/master/docs/Validation-and-Serialization.md) or [express-ajv-swagger-validation](https://github.com/Zooz/express-ajv-swagger-validation) <small><sup>Name change pending</sup></small>
+- **NodeJS:** [fastify](https://github.com/fastify/fastify/blob/master/docs/Validation-and-Serialization.md) or [express-ajv-swagger-validation](https://github.com/Zooz/express-ajv-swagger-validation)
 - **Python:** [connexion](https://github.com/zalando/connexion)
 - **Mojolicious:** [Mojolicious](https://metacpan.org/pod/Mojolicious::Plugin::OpenAPI)
 
@@ -253,6 +341,19 @@ Your test suite can use the descriptions to prove the responses work properly
 
 ---
 
+```rb
+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
+```
+
+<small>https://apisyouwonthate.com/blog/writing-documentation-via-contract-testing</small>
+
+---
+
 ## Request Validation at Gateway
 
 Can't find a middleware?
@@ -357,6 +458,52 @@ validate(userSchema, { ...input, email: 123 );
 
 ---
 
+**How can we enforce style guides for docs?**
+
+https://stoplight.io/spectral <!-- .element: class="fragment" -->
+
+---
+
+```yaml
+rules:
+  schema-names-pascal-case:
+    description: Schema names MUST be written in PascalCase
+    message: '{{property}} is not PascalCase: {{error}}'
+    recommended: true
+    type: style
+    given: '$.components.schemas.*~'
+    then:
+      function: pattern
+      functionOptions:
+        match: '^[A-Z][a-zA-Z0-9]*$'
+```
+
+---
+
+<!-- .slide: data-background="img/studio-spectral.png" data-background-size="contain" -->
+
+---
+
+**Reference Company-Wide Style Guides**
+
+```yaml
+extends:
+  - "https://api.acme.com/style-guide.yml"
+```
+
+---
+
+- Editor (Studio, VS Code coming...)
+- CLI
+- Git Hooks
+- Continuous Integration
+
+---
+
+Consistent APIs = ⏰ 💰 🥳
+
+---
+
 <span style="font-size: 60pt">apisyouwonthate.com</span>
 
 Join our [Slack](http://slack.apisyouwonthate.com/)