OpenAPI Extensions for OSLC
- 1. OpenAPI Extensions for OSLC OSLCFest 2020 Luis Ramírez, Koneksys luis.ramirez@koneksys.com May 19, 2020 1
- 2. whoami ● Software Engineer @ Koneksys since 2019 ● Experienced with web API Technologies ● Former co-founder of SISU Technologies ● Lesson learned: Never underestimate integrations 2
- 3. OpenAPI ● Specification to describe Web API ● Endpoints and Resources ● Format: YAML or JSON ● Originated from Swagger 3 User definition User endpoints
- 4. Swagger 4 Swagger Codegen: Code generation for server stubs and client SDKs. ( OpenAPI - Input) Swagger UI: API Documentation ( OpenAPI - Input) Swagger Core: Java Annotations ( OpenAPI - Output) Set of tools around OpenAPI
- 8. OpenAPI Initiative - Members 8
- 9. Development Approaches (Pipelines) 9 Code First API First
- 10. Code First Approach ● Write code with Swagger Core annotations, then generate OpenAPI. 10
- 11. API First Approach ● Write OpenAPI first, then generate code. 11
- 12. Eclipse Lyo Designer Support For Swagger 12
- 13. Lyo Designer Approach: Code First 13
- 14. OSLC & OpenAPI Integration ● OSLC: Structured endpoints and resources. ○ Swagger UI doesn’t reflect this. ● What if we could add OSLC concepts to OpenAPI? ● Possibilities: ○ Generate OSLC APIs using Swagger Codegen (Eclipse Lyo Designer Codegen Other platforms) ○ Meaningful documentation in Swagger UI 14
- 15. OpenAPI Extensions ● AKA Vendor Extensions ● Example: ○ AWS API Gateway extensions 15
- 16. OpenAPI Extensions ● Properties prefixed with x- ● Read by Swagger Tools ● Examples: Microsoft Flow, Amazon API Gateway, Azure API Management 16
- 17. ● Operations: ○ x-OSLC-ResourceShapeEndpoint ○ x-OSLC-ServiceProvider ○ x-OSLC-Service ○ x-OSLC-QueryCapability ○ x-OSLC-CreationFactory Proposed OpenAPI Extensions for OSLC ● Models: ○ x-OSLC-ResourceShape ● Model Properties: ○ x-OSLC-Name ○ x-OSLC-PropertyDefinition ○ x-OSLC-Occurs ○ x-OSLC-ValueType ○ x-OSLC-ReadOnly ○ x-OSLC-Range 17
- 18. Proposed OpenAPI Extensions for OSLC: Endpoints 18
- 19. Proposed OpenAPI Extensions for OSLC: Resources 19
- 20. Demo: OSLC OpenAPI Extensions Swagger Codegen ● Input: OpenAPI spec file with extensions ● Output: OSLC API ● API First Approach ● Swagger tools have a degree of customization ● Swagger Codegen: Mustache template overrides for generators ○ Generator: JAX-RS Server ○ Output: Spring Boot 20 Swagger Codegen OpenAPI with Extensions Custom templates OSLC API
- 21. Demo 21
- 22. Next Steps ● Swagger Codegen: Include extensions in Swagger Core Annotations in generated code. ○ The generated code can’t produce an OpenAPI spec with the OSLC extensions. ● Formally define and document the extensions. ● Customize Swagger UI (plugin) to show meaningful OSLC data based on extensions. ● Potentially generate OSLC Clients. 22
- 23. Major Challenges ● Swagger UI: Design support for RDF formats in samples. ● No support for OAuth 1.0a. 23
- 24. Open invitation to collaborate! https://github.com/cenobyte321/oslc_openapi_extensions Questions? luis.ramirez@koneksys.com