Uploaded image for project: 'Solr'
  1. Solr
  2. SOLR-17395

Generate v2 API ref-guide content from OpenAPI Spec

    XMLWordPrintableJSON

Details

    • Bug
    • Status: Open
    • Minor
    • Resolution: Unresolved
    • None
    • None
    • documentation
    • None

    Description

      SOLR-16346 created an OpenAPI specification (or "OAS") covering our v2 APIs, and we've since started to use this OAS to generate various other artifacts: Java bindings for SolrJ (SOLR-16825), a Python client (SOLR-16835), a Javascript client.

      The same tooling used to produce the artifacts above can also be used to generate asciidoc content. We should investigate using this to generate content for our ref-guide.

      This benefits will users by ensuring that the documentation they're reading is always up-to-date with any code changes. And it benefits us developers by giving us less content to maintain manually. (Developers will have to pay close attention to annotations in the code that ultimately drive the OAS. But that's probably easier than always remembering to update docs that live in some other part of the source tree entirely.)

      Attachments

        Issue Links

          Activity

            People

              Unassigned Unassigned
              gerlowskija Jason Gerlowski
              Votes:
              0 Vote for this issue
              Watchers:
              1 Start watching this issue

              Dates

                Created:
                Updated: