API Specifications observations

[Keith Furnell]

A few questions/observations with the API Specifications page:

1. The documentation for this feature suggests that committed Swagger/OpenAPI specification(s) are automatically discovered. Does this expect a particular filename or path convention, or require a commit after an existing repo is connected (or is it on a very long poll), as this doesn't seem to be happening for us?
2. The UI (see below) for manually referencing an API/OpenAPI seems clunky:
   1. The fields are unnecessarily narrow
   2. The Repository field appears pre-populated but not selectable/editable, only replaceable, does it default to the component's synced repository?
   3. The tool-tip for the Repository field refers to BitBucket in one place, and both BitBucket and GitHub in another
   4. Could the full URL, including repo and branch etc, be provided rather than requiring users to figure out what substring of that URL is required for the Path field?
   5. There seems to be delay between configuring the API path, and the specification being rendered, during which time it looks like nothing's happening (no status feedback)
   6. There doesn't seem to be an option for adding multiple specifications (as implied by the page name) manually
3. The path to the API doesn't seem to be available in config-as-code?
4. Further to this question, the documentation still seems on the vague side about what types/formats/versions of API specification are supported, and how multiple definitions (e.g. from different linked repositories) get handled.

Manual path configuration UI:

[Aidan Cunniffe]

Thanks for the feedback Keith - it will find any valid OpenAPI file (regardless of name) in the first 2 levels of depth in a repo. Specifically it's looking for `openapi: x.x.x` in a YAML file or `"openapi: "x.x.x"` in a JSON file, and then verifying the rest of that file is valid OpenAPI. 

I logged some of the manual set up frictions. We're also looking at what it will take to move this to config as code (not a lot of work). 

[Keith Furnell]

Thanks, the assumption about location explains a lot (and seem pretty crucial information for https://support.atlassian.com/compass/docs/manage-api-specifications/). I don't think it's a particularly unusual pattern for specifications to reside three levels down within a src/main/resources/ folder.

Please do update this thread if config-as-code support is added though.

Did you see my 5th question (sorry, it got added as an answer)?

[Aidan Cunniffe]

We'll look at updating these now! Just migrated the docs for Compass to a new part of Atlassian support so we've got some updates to make. 

looking at 5 now

[Keith Furnell]

And one more:

5. The Summary column of the Endpoints table not unreasonably seems to display the content of the OpenAPI summary field. However many of our endpoints instead populate the description field. Could the table use this field, where the summary is empty?

[Aidan Cunniffe]

Do you provide both in this case or just description? We could probably make the log `summary || description`

[Keith Furnell]

We only provide one, but someone could obviously provide both. Based on their definitions, summary certainly makes sense to take precedence over description in that case. Note that description could contain CommonMark.