Lifecycle of the Open API spec / Swagger & SmartDocs

[skarlovic]

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 · Accepted solution]

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.

[skarlovic]

@Marsh Gardiner thanks for your response... regarding your comment about

"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."

Does this mean if import a spec and render the SmartDocs, go into the rendered method and edit via the UI, say and description or some other text or sample, but then re-import the spec again because say for example a definition / schema has changed or there is a new endpoint / or operation on an existing endpoint, would the textual changes via the form/UI be preserved in all cases?

Secondly, assuming we want to alter the SmartDocs template to show a sample response for a 200 response or for perhaps the error response schema or sample, what is the best practice doing that? Are there Apigee SmartDocs templates we can use to achieve this? Or do we need to write our own against the internal data model SmartDocs is using?

Thanks again!

Steve

[Marsh]

I'd suggest making edits in the spec rather than via the UI if you plan to make subsequent imports at a later date. The direction that Edge is heading is that the spec is the source of truth at all times.

While you should be able to convince SmartDocs to display 200 response samples, I'm not sure it's worth the effort. I'm also not aware of any examples of this to refer to. Our presumption (which may have been wrong, admittedly) was that by making it easy for developers to make a live request from the docs, developers wouldn't need the example as much (in fact, having info contextual to the user can make it more meaningful, such as retrieving profile data). However, there are times, like when you're dealing with a financial transactions, etc., where an example could be useful. You could consider shimming an example into a description field, but that again seems a bit messy.

[skarlovic]

Thanks for the response Marsh. I appreciate the quick feedback.

[gitesh]

@skarlovic Please look at the sample module here to get client credentials to work with SmartDocs.

https://github.com/giteshk/smartdocs_oauth_additions

You may need to modify the logic on how to generate the actual token, but this module will help modify the UI widgets to support Client Credentials grant.