Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

Version 1 Next »

Goal: Development and Documentation Go Hand-in-hand

  • From Writing API Documentation -> Developing API Documentation

  • Make it easy to create by designers and developers

  • Make it easy to access and relevant to developers

    • Developer engagement

  • Make it easy to use: Sample Calls and Code are essential

    • Try It For Yourself (TIFY) Examples

    • Panes on page with prose, sample code, and navigation / search

    • Keep simple and easy to understand

    • Copy and paste friendly

    • Target languages (and code generation)

Team (please sign up below)

Approach and Steps

Modeling Subcommittee along with the Documentation Project will discuss and recommend to the TSC a common API Documentation approach for ONAP.

  • Style Guide for defining APIs in Swagger / OpenAPI 3.0

  • Use Swagger toolset to develop and publish Swagger / OpenAPI 3.0 API Specs (in JSON or YAML) (e.g., SwaggerHub)

  • Select a tool for generation of API Reference documentation directly from Swagger / OpenAPI files (using Redoc for example which creates a consistent standalone HTML file)

  • Create common and uniform Conceptual API Documentation describing each API and provides quick start and usable TIFY(try it for yourself) samples

    • Start with a common ONAP RST template, instructions, and examples

  • Select and work with a few ONAP projects to pilot the approach for Frankfort (e.g., External API, SO, etc.)


Reference Documentation Generation Tool Candidates


  • No labels