Luis Ramírez presented on using OpenAPI extensions to integrate OSLC concepts into OpenAPI specifications. This would allow generating OSLC APIs using Swagger Codegen and providing meaningful documentation of OSLC resources and services in Swagger UI. Ramírez demonstrated using custom x- properties prefixed in an OpenAPI spec to define OSLC-specific metadata, and generating an OSLC API using Swagger Codegen. Remaining work includes incorporating the extensions into generated code and customizing Swagger UI to surface the OSLC data. Challenges include designing RDF format support in Swagger UI and a lack of OAuth 1.0a support.

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

5. Swagger Codegen
5
Link

6. Swagger UI
6
Link

7. Swagger Core (Annotations)
7

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