Solved: Lifecycle of the Open API spec / Swagger & SmartDo... - Page 2

skarlovic · 11-29-2016 10:21 AM

Here are a few questions we have around the lifecycle of the Open API specification and how it's used in SmartDocs. Any feedback I can get, would be appreciated.

What limitations are there between SmartDocs rendering the Open API specification the contents of the Open API specification. For example we are using OAuth 2.0 with client crendentials grant type is this fully supported in SmartDocs? Will the schema for request and response payloads render? Does SmartDocs support multiple formats (i.e. XML and JSON)? These are just a few of the questions we have... is there a document describing known limitations?

If there is a change to the Open API specification because, for example new query parameters or response attributes are now supported and we want the documentation to represent these changes. If we make the schema changes and add the new query parameters in the Open API specification, how can we import the new changes without losing/altering existing content and styling added directly in the portal itself?

We've explored apigee2openapi and Apigee OpenApiGen http://specgen.apistudio.io/open-api/30be06a1-267b-40d7-943d-365c55b4caf2/run-api and both seem to generate part of the Open API specification, leaving some of it to be added manually. Is there a specific workflow a team should follow in order to create/generate an Open API specification and maintain it as the proxy changes over time.

What is the best practice for changes made to the Open API specification? Specifically, API developers need to write some technical aspects of the specification and tech writers should write some of the descriptions at a minimum. Is it recommended to have both groups working on the same specification file? Or would tech writers update the specification in the developer portal only?

Marsh

SmartDocs does not support client credentials out of the box. I believe some custom work was done to enable this, maybe @Gitesh Koli can chime in? As for schemas, only the request schema is supported today (assumption was that inspecting an actual response would be meaningful enough).

When you change your spec, today's workflow would be to re-import the spec and re-render the docs. Any changes you might make to your templates and CSS would remain intact and be applied.

The two tools you mentioned both exist to help those unfamiliar with the OpenAPI Specification syntax and to take advantage of any structure already defined in a proxy. We recently announced the next-generation approach to working with specs in Edge (see the new Apigee Edge experience announcement) but note that this approach only works with the new developer portals at this time.

As for your collaboration question, today developers and writers would work on the same spec. However, as we continue down the path of working with specs in Edge, we're looking at ways in which tech writers might edit only descriptions, for example.

View solution in original post

Lifecycle of the Open API spec / Swagger & SmartDocs