OpenAPI documentation for microservices

[lauracowen]

Target audience: developer of a microservice

Some background: OpenAPI is a mechanism for generating structured documentation (eg HTML pages) of the APIs in a microservice. When you have written an API for your microservice, you can generate documentation about it so that other developers can look up how to use your API in their own microservice (so that their microservice can call yours). There are alternative ways to create the API doc, including writing the API doc first and generating the API itself from the doc. The OL OpenAPI guide (see below) describes the different approaches nicely.

In the topic, introduce MP OpenAPI, mention the multiple approaches (all are shown in the guide so we need to support that) but talk primarily about the annotations approach. Then the alternative approaches and when is most appropriate to use each of them. Explain it simply as in the guide, not directly taken from the spec (the guide explains it much more clearly).

See also the KC topic but don't include the 'avoid trouble' box from the KC topic; instead, move that info into a separate general troubleshooting topic (talk to Laura/Alasdair about where this should go) and then link to the troubleshooting topic.

Sources of info:

• https://www.ibm.com/support/knowledgecenter/en/SSEQTP_liberty/com.ibm.websphere.wlp.doc/ae/twlp_mpopenapi.html
• http://download.eclipse.org/microprofile/microprofile-open-api-1.0/microprofile-openapi-spec.html
• http://download.eclipse.org/microprofile/microprofile-open-api-1.1/microprofile-openapi-spec.html#_programming_model
• http://download.eclipse.org/microprofile/microprofile-open-api-1.1/microprofile-openapi-spec.html#_static_openapi_files
• http://download.eclipse.org/microprofile/microprofile-open-api-1.1/microprofile-openapi-spec.html#_filter

Related links to include:

• Guide: Documenting RESTful APIs https://openliberty.io/guides/microprofile-openapi.html <- worth reading this to understand it before talking to Arthur (or whoever he suggests you work with in dev).
• relevant Javadoc
• OpenAPI project documentation about how to customise the style sheet of your OpenAPI user interface (there is a KC topic about this but there's no point duplicating what the online project doc contains - check what it contains and whether this is the case).

Background research:

• https://openliberty.io/guides/microprofile-openapi.html
• google for 'OpenAPI' ('Swagger' is the old name for the project).

Contact:

• Arthur De Magalhaes - ask him who should be the dev contact for OpenAPI

[lauracowen]

Review feedback on the draft doc published at https://draft-openlibertyio.mybluemix.net/docs/ref/general/#mp-openapi.html

Good start. In general, while being technically accurate, it needs filling out a bit to make it easier to read and understand the points being made. The topic (as all the topics in the docs) needs to take an "inverted pyramid" approach to presenting information (https://en.wikipedia.org/wiki/Inverted_pyramid_(journalism)). Primarily, as the Wikipedia article says: "readers can leave the story at any point and understand it, even if they do not have all the details.". Provide the most important information (to the developer reading it) first, then less important details later - only a reader who's interested will read on but all readers will get what they need from the topic.

Introductory section

In the introductory section, the second paragraph needs to summarise what the "multiple ways" are - instead of expecting the reader to carry on reading. The sections below the paragraph will then just expand on the details (that's if the reader wants to know more - they may not but at least they'll know for sure that they don't - instead of having to wade through the whole topic before they decide, or worse just leave the topic because they can't be bothered and then are left unsure about whether the topic actually answers their questions).

How about something like this (based on info in the OpenAPI guide and my basic understanding - so get it tech reviewed again!):

"OpenAPI (previously known as Swagger) defines a standard interface for documenting and exposing RESTful APIs. This standard interface enables both humans and computers to understand or process the capabilities of a web service that are available through its REST API without requiring direct access to the underlying source code of the web service. MicroProfile OpenAPI provides a set of Java interfaces and programming models that enable Java developers to natively produce OpenAPI documents from their JAX-RS applications.

Another developer can only use the REST API in their own web service (e.g. to request information) if they know what information they can request from the API and what information the API needs from them to be able to return relevant information. (re-word this to make a bit more sense!) It is important to document APIs when they are published so that other developers can use them.

There are two main ways to generate an link:https://swagger.io/docs/specification/about/[OpenAPI] document. The developer can generate documentation of the REST API from the source code of the REST API itself. This produces a reference document that lists all the API endpoints and descriptions of how to use them. Alternatively, the developer can start by designing the API in the form of structured documentation that they can then augment with annotations in the code. The developer can even generate the stubs for the source code (including client libraries for the API) from this manually-created documentation."

Sub-sections of the topic

Currently, the sub-sections in the topic, whilst technically accurate, don't give much context to the technical information, so it's not clear what they're referring to. For example, with the last sentence of the introductory section ending with "…in multiple ways.", it would be reasonable for the reader to expect that each of the five sub-headings is one of those multiple ways of generating API docs, when that's not actually the case. Again, it just needs more writing around it (and more meaningful headings) to make it easier for the reader to understand what they're reading and to know what's relevant or not to them.

Annotations section

So, you could change the heading "Annotations" from focusing on the technology to something more focused on what the user gets from it, such as "Generated REST API documentation".

Then the section can explain that you generate documentation for the REST APIs that you write by adding annotations to your JAX-RS code. JAX-RS framework handles the basic API docs generation but by adding annotations to your code, you can provide more useful explanation of the parts of the API.

I don't think it's necessary to say that "MP OpenAPI processes JAX-RS annotations by default." (I know the guide says that but I'm not sure it gives much value). The important thing is that the developer wants API documentation, JAX-RS can generate most of it, but the developer can and probably should provide additional details/explanation about the methods etc.

Don't talk about "vendors" - that refers to projects/companies who are implementing the spec - the developer doesn't care how or why it was implemented - they just want to use the implementation. Going back to the 'inverted pyramid' approach, how JAX-RS generates the docs is not as important to the developer as what they can or should do. So focus on that first. The less value a piece of information has to the reader, the later on it should be presented to them (there's no correct/incorrect answer to doing this, it just takes practice and thought).

Give an explanation of what the annotations are for and why you'd use them as a developer of a RESTful API:
"For example, the following code example shows some JAX-RS code to request the list of host names in the inventory. The code has been annotated with OpenAPI annotations to provide more useful and explanatory information about the operation:

    @GET
    @Produces(MediaType.APPLICATION_JSON)
    @APIResponse(
        responseCode = "200",
        description = "host:properties pairs stored in the inventory.",
        content = @Content(
            mediaType = "application/json",
            schema = @Schema(
                type = SchemaType.OBJECT,
                implementation = InventoryList.class)))
    @Operation(
        summary = "List inventory contents.",
        description = "Returns the currently stored host:properties pairs in the "
        + "inventory.")
    public InventoryList listContents() {
        return manager.list();
    }

In the following OpenAPI documentation example that is generated from the example code, the JAX-RS framework generates the path /inventory/systems based on the value of the @Path annotation, and the value of the operationId key (listContents) based on the name of the method (listContents()). The other parts of the document are generated from the OpenAPI annotations with which the developer annotated the code. For example, the @Operation annotation provides more meaningful information about what the operation does and why; in this case, the operation returns a list of the host names with properties of each host that are currently stored by the inventory web service. This is described by the summary and description keys in the @Operation annotation:

/inventory/systems:
  get:
    summary: List inventory contents.
    description: Returns the currently stored host:properties pairs in the inventory.
    operationId: listContents
    responses:
      200:
        description: host:properties pairs stored in the inventory.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InventoryList'

The information provided through the OpenAPI annotations augment the basic API documentation that is generated by the JAX-RS framework."

Remove the paragraph starting "Annotations like @callback…" as that's about what annotations are - we should be able to assume the developer knows that to be reading this topic or writing modern Java.

The paragraph starting "When the same annotation is used…" is useful though the examples given need more clarification (eg what are @Server and @tag annotations examples of and how are they demonstrating the precedence point you've just made?).

It's good that you've found annotation examples and you're right not to reproduce that whole set of info in this topic, but those examples should be in the annotations Javadoc so that you can just link to them from this topic (I've raised an issue to update the Javadoc - we'll see what the developers say and, if it gets done, you can add a bit to this topic saying that examples of the annotations are available in the relevant Javadoc). In the meantime, you could link to the higher level javadoc page for a list of available OpenAPI annotations - check this link with the tech reviewer.

Static OpenAPI files section
The purpose of this section is about the developer manually creating the documentation instead of generating it from the API. So maybe use the heading "Manually created REST API documentation"?

Start by introducing the idea of manually creating the API doc and that the approach is focused on designing the API before implementing it (the third and fourth sentences in your first para are alluding to this in a roundabout way but need to be more concrete). Don't talk about the /openapi location at the start of the section - focus instead on what the developer cares about most: what does it mean to manually create the doc and why would you do it when the alternative is to generate it from the API automatically?

"lock in the API contract" is too jargon-y, and "client and provider" isn't very clear who you're talking about. The point that you've got about enterprises is about how, in an enterprise (or big company), you need consistent, usable APIs so APIs should be designed and reviewed/approved, not just cobbled together. Doing that up-front means that you then have a document that's agreed between the relevant people that that's a good API design, and the API must be implemented following that design.

Then give the basic details about what format the doc file should be in (json/yaml) and the location in which it should go.

Then something about how you can use create a complete doc or just a partially complete doc manually, that can be augmented by adding annotations in the code as described in the previous section.

Link to the OpenAPI guide to give an example of a well-structured complete yaml file (unless your tech reviewer can give you a nice short example to include here and explain concisely, which would be nicer - can link to the guide as well for a longer version).

Programming model section
I think just remove this section completely. I think this is the less straightforward alternative to using the annotations. Let's focus on the annotations in this topic. If we want a more advanced approach, we can write more topics later.

Filter section
This section starts by talking about OASFilter but OASFilter is not what's important to the developer at this stage. The developer wants to know why they should care about filtering and what is actually being 'filtered' and why (incidentally, I don't think the guide explains this well either). I think you need to ask the tech reviewer to explain what's being filtered (I think it's just filtering components in and out of the generated doc) and, importantly, why.

Provide an example of a filter method from the guide (see https://openliberty.io/guides/microprofile-openapi.html#filtering-the-openapi-tree-elements).

It might make sense to move this section to be a sub-section of the generating doc section above (as it's only really relevant to the generated doc - if you were writing the doc manually, I think you'd just leave it out? check that assumption with the tech reviewer though).

OpenAPI UI section
Change heading to something like "Viewing and formatting API documentation" or something (not sure)?

This section needs to introduce what the UI is. Start by saying that the documentation that is generated or manually created is available at xxx endpoint of your web service.

Then you can say that the format of the doc is defined by a default stylesheet but you can optionally customize the stylesheet.

Don't link from the OL docs to the KC. If we need info from the KC, we need to write it in the OL docs (raise an issue on the OL docs backlog if necessary). In this particular case, it might be that you can provide a condensed version of the KC info in this section (I'm not sure - it might be too much but you could give it a go and see if it makes this topic look too long). It might be we need to move this whole section to its own topic, but keep it here for now and we can see how it looks.

/cc @Charlotte-Holt @NottyCode

[ManasiGandhi]

Draft link for the issue https://draft-openlibertyio.mybluemix.net/docs/ref/general/#mp-openapi.html

[lauracowen]

I don't see any changes in the topic on the draft website or in the draft branch in GitHub. Can you check that you've pushed any changes?

[lauracowen]

Also, can you change the topic title to "Documenting microservice APIs with OpenAPI" as it's more meaningful.

[ManasiGandhi]

@lauracowen I'm working on the changes you suggested. I added the draft link during a meeting as it was suggested. Will update your edit suggestions in the doc and update in the issue.

[lauracowen]

Thanks for making the changes to the first part of the article. I've some comments on that but also can you address the later sections with the feedback I gave previously?

• I think you can remove the first paragraph completely (sorry, I know my previous feedback talked only about the second para).
• "Developers can communicate with the REST API in their web service only if they have the relevant information to do so." - yes, though I think it need to be a bit more explicit; eg "Developers can write a web service to communicate with the REST API of a second web service only if they have the relevant information to do so. A developer needs to understand what information their web service can request from the second web service using its REST API and what information the API needs from the first web service in order to be able to return the relevant information."?
• Heading "Processing annotations" -> "Processing annotations to geenerate REST API documentation" - I think it needs to be more explicit, otherwise, it's not very obvious what the relevance of this first heading/section is.
  • In that section, I think there needs to be a little more introduction. eg alter the first sentence/para to "You can easily generate basic API documentation from a JAX-RS application; the JAX-RS framework handles that for you. You should, however, provide more useful explanations of the parts of the API where appropriate by adding annotations to your code. The annnotations are then processed to provide more detailed and useful documentation about how to use the REST API." (or something like that)
  • In the paragraph before the first example, I think it doesn't need to start with "For example," afterall. Just starting at "The following code example shows…".
  • "generates the path /inventory/systems path based on" looks like it has an extra "path" in it and the path itself should be highlighted appropriately.
  • The annotations and method names etc also need to be highlighted appropriately in the text.
  • I think maybe the para between the Java and the output examples could do with being a bit clearer. eg change the start to "The example Java code generates the following OpenAPI documentation. The /inventory/systems path is based on the value…". Change "that the developer annotated the code with." to "in the code.".
  • I think you can remove "This is described by the summary and description keys in the @operation annotation:".
  • Arthur has confirmed that they will be adding the annotation examples and static file examples to the Javadoc. So I think remove the line "For examples of annotations…". And replace with something like "See the MicroProfile OpenAPI Javadoc for the annotations available." and link the "MicroProfile OpenAPI Javadoc" bit to somewhere like https://www.openliberty.io/docs/ref/microprofile/3.0/#package=org/eclipse/microprofile/openapi/annotations/package-frame.html&class=org/eclipse/microprofile/openapi/annotations/Operation.html (but find out how to make it version agnostic - the MP OpenAPI javadoc for annotations looks oddly packaged in that it's all separated out into separate packages so maybe also find out which package or place in the Javadoc is the most useful to link to).
• "Manually created…" section - I'm still not sure about the way this is explained, though I think the points are generally correct.
  • "An alternative approach is to design the REST API in an editor, such as the Swagger editor, before writing any code. This approach enables you to spot any problems in the design before, rather than after, implementation. In large companies, it is important to have consistent, usable APIs that have been reviewed and agreed by the relevant people that it is a good API design. This API design then forms a contract and must be implemented as agreed."
  • Then "You can write this API design in YAML or JSON which can then be used to generate the documentation and, optionally, even stubs for the API code itself. You can then also augment the documentation with annotations in the code as described previously."
  • You need to link either to the OpenAPI guide for an example of a well-structured complete yaml file (unless your tech reviewer can give you a nice short example to include here and explain concisely, which would be nicer - can link to the guide as well for a longer version).
  • Can you provide a link to the Swagger editor (or something about it) as it's not been mentioned so far and doesn't get explained at all - it's probably what it says it is so a link would probably be sufficient?
  • Link to the relevant Javadoc instead of to the static file examples.
• "Filter" section
  • Rename this heading to "Filtering components in and out of API documentation" or similar.
  • Talk to the SME or investigate further what this is about and write about it. See my previous comment about what should be covered.
  • For the examples, ask Arthur if it's appropriate to include the linked OASFilter samples (from the wiki) in the Javadoc (https://openlibertyio/docs/ref/microprofile/3.0/#class=org/eclipse/microprofile/openapi/OASFilter.html&package=allclasses-frame.html) (like I asked about the other two sets of samples - he might ask you to create an issue in the same way if he agrees). Then link to the Javadoc.
• "Viewing and formatting" section
  • I think this needs to be clearer. Replace with eg "The documentation that is generated for the REST API is available at the /openapi endpoint of your web service. The documentation is formatted using the standard OpenAPI user interface (UI) and a default style sheet. You can optionally customise the style sheet for your web service." (check these details with the SME)
  • See my previous comment having a go at including a concise set of the info from the KC topic here (ie don't make it into 'task' info; instead provide the list (table?) of rules about the CSS, also a quick description of where the CSS file should go, and mention of the MP Config property. When you've done that, I'll take a look.

[lauracowen]

Thank you - looking better.

• "generates the path /inventory/systems path based on" still seems to have something odd about it. I don't think both instances of "path" should be there, and "path" shouldn't be highlighted as monospace. Can you check the readability of the sentence or get someone to give second pair of eyes if it's all starting to swim from staring at it too long? :)
• I don't think you've addressed:
  • The annotations and method names etc also need to be highlighted appropriately in the text. ["listContents" and "listContents()" should be highlighted appropriately as one is a value and one a method, I think.]
  • I think maybe the para between the Java and the output examples could do with being a bit clearer. eg change the start from "In the following OpenAPI documentation example code, the JAX-RS framework generates the path /inventory/systems path based on the value..." to "The example Java code generates the following OpenAPI documentation. The /inventory/systems path is based on the value…". Change "that the developer annotated the code with." to "in the code.".
• Something's gone wrong with the asciidoc syntax for the "Manually created..." heading.
• I don't think you've addressed:
  • You need to link either to the OpenAPI guide for an example of a well-structured complete yaml file (unless your tech reviewer can give you a nice short example to include here and explain concisely, which would be nicer - can link to the guide as well for a longer version).
  • Can you provide a link to the Swagger editor (or something about it) as it's not been mentioned so far and doesn't get explained at all - it's probably what it says it is so a link would probably be sufficient?
  • Link to the relevant Javadoc instead of to the static file examples.
• I like the opening sentences of the Filtering section now but I don't think it's useful to link to the OASFilter java class in GitHub. I'm also not sure what that "With OASFilter..." sentence is saying and how it relates to the previous sentences.
• I don't think we should be linking to the OASFilter Samples on a wiki. Can you talk to Arthur and ask him if the OASFilter stuff is really important to someone using OpenAPI? And whether we should be documenting it in the OL docs (and how high priority it is for someone to use OpenAPI).
• Otherwise, this filtering section is okay but needs the sentences grouping into paragraphs more.

[lauracowen]

I'm moving this out of 'ready to publish' because I think it needs an editorial/proofread review. There are minor grammatical/punctuation/spelling typos (eg "port" instead of "part").

Also, has this topic been re-reviewed by the technical SME since making significant changes to the wordings? If so, please record it here (there needs to be a record - ideally paste in the feedback you received from him here too). If not, can you get them to check the assertions made in this topic?

We shouldn't link to the spec from docs - the spec is written for the app server developers (eg the Open Liberty dev team) to implement, not for the end-user. If the filters are useful to the end-user (developer), which I think they seem to be, this topic should contain a short section explaining what they are and why they are worth using. I think you had an ok filtering section before that just needed tidying up.

Link to Javadoc - I don't see any lists of annotations at that link, can you check it? I think my issue to add all the examples to the Javadoc is still not addressed (microprofile/microprofile-open-api#405) so if that's what you were intending to link to, maybe it's not worth doing for now. Might just have to link to the wiki page like you've done further down for the filter samples. I don't think we should be linking to the wiki really but we might need to for the short-term then update the links later. Can you create an issue on the docs backlog to update any links in this topic that currently point to the wiki to point to the javadoc? Provide a link to my github issue so we can check from time-to-time if it's been fixed yet.

Can you also provide a link to the MP OpenAPI guide?

Also, don't abbreviate to "MP OpenAPI". Just use the full name.

[ManasiGandhi]

Artur's comments,
"Hi, I think it looks good. Just found a typo I think
Adding annotations takes less work and gives useful explanation of the different ports of the API.
should be parts I guess"

[ManasiGandhi]

@lauracowen Can you review this draft
https://draft-openlibertyio.mybluemix.net/docs/ref/general/#mp-openapi.html

[ManasiGandhi]

@chirp1 Can you review this draft
https://draft-openlibertyio.mybluemix.net/docs/ref/general/#mp-openapi.html

[msmiths]

Just a couple of comments this time:

The code-first approach

1. The second paragraph states that the @APIResponses, @Operation, and @Parameter annotations have been added to two JAX-RS methods, getPropertiesForHost() and listContents(). However, the code sample only includes a single method called purchaseCar().
2. The previous version of the document included the OpenAPI YAML that is generated but no code to indicate what the YAML snippet was generated from. The current version includes the code but no OpenAPI YAML. The example needs to show BOTH the code with the annotations and the OpenAPI YAML that is generated from the code.

[ManasiGandhi]

@msmiths Here is a link to the draft with the updates https://draft-openlibertyio.mybluemix.net/docs/21.0.0.2/documentation-openapi.html

• The second paragraph states that the @APIResponses, @operation, and @parameter annotations have been added to two JAX-RS methods, getPropertiesForHost() and listContents(). However, the code sample only includes a single method called purchaseCar().
• The previous version of the document included the OpenAPI YAML that is generated but no code to indicate what the YAML snippet was generated from. The current version includes the code but no OpenAPI YAML. The example needs to show BOTH the code with the annotations and the OpenAPI YAML that is generated from the code.

[msmiths]

@ManasiGandhi That looks better. No further comments from me.

[dmuelle]

Content review

Nice work on this!

Intro

• I think you can replace "The MicroProfile OpenAPI specification" with "MicroProfile OpenAPI " throughout the doc .
• Mention the Mp OpenAPI feature in the introduction. The feature is the relevant unit of function in the OL context and that's consistent with our other MP docs. Link to the feature page on the first mention. Use the macro- You can implement MicroProfile OpenAPI for Open Liberty by enabling the feature:mpOpenAPI[display=MicroProfile OpenAPI] feature
• Structured documentation helps other microservices and developers to understand and communicate with your web service +
  In the shortdesc, you refer to JAX-RS applications, but here you refer to "web service". I don't think "web service" is the best term here, as web services might be more associated w/ JAX-WS, Http, SOAP, rather than REST APIs and JAX-RS. I know Laura suggested web service and it may be that it is a generic term but I think you could just say "JAX-RS application" or even just "application". I would avoid using the term web service throughout.
• There are two main approaches to generate an OpenAPI document, the code-first approach and the design-first approach. +
  rewrite this to remove the explicative construction "There are"
• When you introduce the code-first approach, mention that its accomplished by adding annotations. This will help orient the reader in the following section. Maybe: `In the code-first approach, a developer can generate documentation of the REST API from annotations that are specified in the source code."
• Replace "Thus" with "Therefore". Thus is archaic
• What is "the OpenAPI tree"? I think this term needs to be explained. Its not mentioned in the MP OpenAPI spec and a google search doesn't produce a ready definition. IO know the guide uses it but it's not defined there either.
• Additionally, you can generate the stubs for the source code, including client libraries for the API, from this manually created documentation. +
  What is the value of creating stubs? They are mentioned but not explained. I don't think you need to explain the concept but you could provide context by giving a concise indication of who would want to do this and why

The code-first approach

• In the code-first approach, you can initially generate basic API documentation from your JAX-RS application; the JAX-RS annotations are processed by default. Then, you can augment the existing JAX-RS annotations with OpenAPI annotations, which are processed to generate the documentation.+
  Does this mean that that a basic API document is generated by default from JAX-RS annotations? Its not clear. The last sentence at the end of this section explains somewhat, but I think something is missing here. Looking back at Lauras comments, she says:+
  "I don't think it's necessary to say that "MP OpenAPI processes JAX-RS annotations by default." (I know the guide says that but I'm not sure it gives much value). The important thing is that the developer wants API documentation, JAX-RS can generate most of it, but the developer can and probably should provide additional details/explanation about the methods etc."+
  "JAX-RS framework handles the basic API docs generation but by adding annotations to your code, you can provide more useful explanation of the parts of the API." <-- I think that gives a good indication of the functional value of both JAX-RS and OpenAPI annotations

• Following is the corresponding OpenAPI document that is generated in a YAML format:

• I think this needs to be rewritten so that "following" is not the subject of the sentence. I also think you should mention that YAML is the default response format, but that the documents can also be provided in JSON format.

• the link to the javadoc will need to be updated for MP 4.0 before this goes to publish. The new javadoc will be available the week before the release.

The design-first approach

• suggested edit: "An alternative approach is to design the REST API in an editor to begin with, such as the Swagger editor , before you write any code."
• suggested edit: "With this approach, you can spot and rectify any issues in the design before implementation it is implemented."
• In large companies, it is important to have consistent and usable APIs, which can be reviewed by subject matter experts to verify the quality of the API design.+
  rewrite this to remove the explicative construction "it is..."
• You can write this API design in YAML or JSON, which can then be used to generate the documentation. Do you mean you can write the design in a YAML or JSON document ? I think you could provide just a little more info based on the guide section you link to in order to clarify. It needs to be more concrete here. The KC page says "Use a text editor to write a static OpenAPI document in either YAML or JSON format, then place the openapi.yaml, openapi.yml, or the openapi.json file in the META-INF directory of your application.", which I think makes it more clear of what you would actually do with the design first approach.
• I think you can reduce wordiness in this section buy removing words like also, even, then.

Filter components in and out of API documentation

• This section seems to have shrunk, based on the previous comments. Per Laura's comment above, avoid linking to the spec. I think you can provide more info here and link to the filtering section of the guide instead.
  She also said: Provide an example of a filter method from the guide (see https://openliberty.io/guides/microprofile-openapi.html#filtering-the-openapi-tree-elements). Not sure if that ever made it into the doc or if it was removed for a reason.

Viewing and formatting API documentation

• Avoid using gerunds, since this is not a task. I'm not sure "formatting" is even covered here?

• This section seems unnecessarily vague

  • Does this information apply to both code and manually generated API docs?
  • Is the value of viewing the endpoint so you can verify your API doc? Or is this how someone else would obtain the info?
  • I think you should explain the utility of adding `/ui' to the endpoint, ie allows you to view the doc in the swagger ui. As Laura mentioned "This section needs to introduce what the UI is"
  • can you provide an example URL? The KC provides https://Liberty_host:https_port/openapi/ui.

  I agree with Martin that we should at least provide a link to the release notes so someone can understand breaking changes. I think you could add a brief statement that some deprecated annotations were removed between 1.1 and 2.0, resulting in potential breaking changes for any consumers of MP OpenAPI who were using those features. And then link to the release notes link he provided for more info.

[ManasiGandhi]

@dmuelle I worked on your reveiw

• I think you can replace "The MicroProfile OpenAPI specification" with "MicroProfile OpenAPI " throughout the doc.

• Mention the Mp OpenAPI feature in the introduction. The feature is the relevant unit of function in the OL context and that's consistent with our other MP docs. Link to the feature page on the first mention. Use the macro- You can implement MicroProfile OpenAPI for Open Liberty by enabling the feature:mpOpenAPI[display=MicroProfile OpenAPI] feature.

• Structured documentation helps other microservices and developers to understand and communicate with your web service +
  In the shortdesc, you refer to JAX-RS applications, but here you refer to "web service". I don't think "web service" is the best term here, as web services might be more associated w/ JAX-WS, Http, SOAP, rather than REST APIs and JAX-RS. I know Laura suggested web service and it may be that it is a generic term but I think you could just say "JAX-RS application" or even just "application". I would avoid using the term web service throughout.

• There are two main approaches to generate an OpenAPI document, the code-first approach and the design-first approach. +
  rewrite this to remove the explicative construction "There are"

• When you introduce the code-first approach, mention that its accomplished by adding annotations. This will help orient the reader in the following section. Maybe: `In the code-first approach, a developer can generate documentation of the REST API from annotations that are specified in the source code."

• Replace "Thus" with "Therefore". Thus is archaic

• What is "the OpenAPI tree"? I think this term needs to be explained. Its not mentioned in the MP OpenAPI spec and a google search doesn't produce a ready definition. IO know the guide uses it but it's not defined there either. Leaving as is. Researched the term and "tree" is a common term used by developers for a data structure.

• Additionally, you can generate the stubs for the source code, including client libraries for the API, from this manually created documentation. +
  What is the value of creating stubs? They are mentioned but not explained. I don't think you need to explain the concept but you could provide context by giving a concise indication of who would want to do this and why

• In the code-first approach, you can initially generate basic API documentation from your JAX-RS application; the JAX-RS annotations are processed by default. Then, you can augment the existing JAX-RS annotations with OpenAPI annotations, which are processed to generate the documentation.+
  Does this mean that that a basic API document is generated by default from JAX-RS annotations? Its not clear. The last sentence at the end of this section explains somewhat, but I think something is missing here. Looking back at Lauras comments, she says:+
  "I don't think it's necessary to say that "MP OpenAPI processes JAX-RS annotations by default." (I know the guide says that but I'm not sure it gives much value). The important thing is that the developer wants API documentation, JAX-RS can generate most of it, but the developer can and probably should provide additional details/explanation about the methods etc."+
  "JAX-RS framework handles the basic API docs generation but by adding annotations to your code, you can provide more useful explanation of the parts of the API." <-- I think that gives a good indication of the functional value of both JAX-RS and OpenAPI annotations

• Following is the corresponding OpenAPI document that is generated in a YAML format:

• I think this needs to be rewritten so that "following" is not the subject of the sentence. I also think you should mention that YAML is the default response format, but that the documents can also be provided in JSON format.

• the link to the javadoc will need to be updated for MP 4.0 before this goes to publish. The new javadoc will be available the week before the release.

• suggested edit: "An alternative approach is to design the REST API in an editor to begin with, such as the Swagger editor , before you write any code."

• suggested edit: "With this approach, you can spot and rectify any issues in the design before implementation it is implemented."

• In large companies, it is important to have consistent and usable APIs, which can be reviewed by subject matter experts to verify the quality of the API design. rewrite this to remove the explicative construction "it is..."

• You can write this API design in YAML or JSON, which can then be used to generate the documentation. Do you mean you can write the design in a YAML or JSON document ? I think you could provide just a little more info based on the guide section you link to in order to clarify. It needs to be more concrete here. The KC page says "Use a text editor to write a static OpenAPI document in either YAML or JSON format, then place the openapi.yaml, openapi.yml, or the openapi.json file in the META-INF directory of your application.", which I think makes it more clear of what you would actually do with the design first approach.

• I think you can reduce wordiness in this section buy removing words like also, even, then.

• This section seems to have shrunk, based on the previous comments. Per Laura's comment above, avoid linking to the spec. I think you can provide more info here and link to the filtering section of the guide instead.
  She also said: Provide an example of a filter method from the guide (see https://openliberty.io/guides/microprofile-openapi.html#filtering-the-openapi-tree-elements). Not sure if that ever made it into the doc or if it was removed for a reason.

• Avoid using gerunds, since this is not a task. I'm not sure "formatting" is even covered here?

• Does this information apply to both code and manually generated API docs?yes

• Is the value of viewing the endpoint so you can verify your API doc? Or is this how someone else would obtain the info?(Martin commented, "The raw OpenAPI document can be retrieved using the /openapi endpoint. In order to see the documentation in the Swagger UI, you need to point a browser at the /openapi/ui endpoint."

• I think you should explain the utility of adding `/ui' to the endpoint, ie allows you to view the doc in the swagger ui. As Laura mentioned "This section needs to introduce what the UI is"

• can you provide an example URL? The KC provides https://Liberty_host:https_port/openapi/ui.

[dmuelle]

Hi @ManasiGandhi - changes look good, just a few more items in the new draft:

Intro

• You can also use a set of predefined models to manually create all elements of the OpenAPI tree.
  Even if you don't need to explain the OpenAPI tree, this sentence seems unnecessarily vague. What the models are or how you might use them is not mentioned anywhere in the topic. If this concept is important to understanding the design-first approach, I think you need to include more info about what the models are or how someone finds/uses them. Otherwise, I recommend removing this sentence as it doesn't add anything concrete to the topic.

• suggested edit:
  Additionally, you can generate the stubs to test your source code, including client libraries for the API, from this manually created documentation.
  --->
  Additionally, you can generate the stubs to test your source code from this manually created documentation, including client libraries for the API,.

The design-first approach

• In large companies, APIs need to be consistent and usable, which can be reviewed by subject matter experts to verify the quality of the API design.
  I think this sentence might have gotten smushed- seems like its trying to say two things at once. Also, I think APIs need to be consistent and usable whether in a large company or not. But SMEs can review the API to ensure it's consistent and usable.

• You can augment the documentation with annotations in the code as described. This is still vague. Maybe something like
  "The code first and design-first approaches are not mutually exclusive. You can augment manually created API documents by adding annotations to the code as you would in a code-first approach."

Filter components in and out of API documentation

This section seems very sparse. Can you apply filters to manually-created API docs? If not, I'd recommend moving this section to be a sub-section of the code first approach. If so, make it clear that you can apply filters either in the code or to the manually created docs.

I also think you need a concise statement of the value of filtering. Why might someone want to add or remove content?
With filters, you can implement an interface in your application. So when a component of the documentation is processed, it calls your implementation and you can either add or remove content.
This is focused on the how, and not the why. I think a user can go to the guide to find out how, b ut if you tell them the why, they can decide here if they care enough to follow up.

Instead of linking on the word "filters", I'd recommend adding a sentence to the end of the section that says, "For more information, see [Filtering the OpenAPI tree elements].

View API documentation

This section is also really thin. I think you should introduce the UI and explain the difference in obtaining the "raw" document vs the ui, per Martin's comment.

Also for the example URL, it shouldn't be hyperlinked to "endpoint"- because it doesn't resolve to anything. I was suggesting to provide that example for how a user might construct their own URL. Like:

"You can view the API documents by pointing your browser to the endpoint URL, for example http://localhost:9443/openapi/ui, where where localhost is your hostname and 9443 is the port number for your application. "

That is consistent with how we have demonstrated endpoint URLs elsewhere in the OL docs but verify with the SME that it is a viable example in this case.

Some deprecated annotations were removed between 1.1 and 2.0 resulting in potential breaking changes. For more information, see Release Notes for Microprofile OpenAPI 2.0
--->
Some deprecated annotations were removed between Microprofile OpenAPI versions 1.1 and 2.0, which might result in breaking changes between those versions. For more information, see the Release Notes for Microprofile OpenAPI 2.0

[ManasiGandhi]

Hi @dmuelle - I worked on your edits. https://draft-openlibertyio.mybluemix.net/docs/21.0.0.3/documentation-openapi.html

• You can also use a set of predefined models to manually create all elements of the OpenAPI tree.

  Even if you don't need to explain the OpenAPI tree, this sentence seems unnecessarily vague. What the models are or how you might use them is not mentioned anywhere in the topic. If this concept is important to understanding the design-first approach, I think you need to include more info about what the models are or how someone finds/uses them. Otherwise, I recommend removing this sentence as it doesn't add anything concrete to the topic.

• suggested edit:

  Additionally, you can generate the stubs to test your source code, including client libraries for the API, from this manually created documentation.
  --->
  Additionally, you can generate the stubs to test your source code from this manually created documentation, including client libraries for the API,.

The design-first approach

• In large companies, APIs need to be consistent and usable, which can be reviewed by subject matter experts to verify the quality of the API design.

  I think this sentence might have gotten smushed- seems like its trying to say two things at once. Also, I think APIs need to be consistent and usable whether in a large company or not. But SMEs can review the API to ensure it's consistent and usable.

• You can augment the documentation with annotations in the code as described. This is still vague. Maybe something like

  "The code first and design-first approaches are not mutually exclusive. You can augment manually created API documents by adding annotations to the code as you would in a code-first approach."

• Filter components in and out of API documentation

This section seems very sparse. Can you apply filters to manually-created API docs? If not, I'd recommend moving this section to be a sub-section of the code first approach. If so, make it clear that you can apply filters either in the code or to the manually created docs. (Artur mentioned that filtering is for advanced use cases, so the section is short. "Can you apply filters to manually-created API docs", Martin mentioned in his comments that filtering is done before the document is generated. I slacked Martin, waiting for his response)

I also think you need a concise statement of the value of filtering. Why might someone want to add or remove content?
With filters, you can implement an interface in your application. So when a component of the documentation is processed, it calls your implementation and you can either add or remove content.
This is focused on the how, and not the why. I think a user can go to the guide to find out how, b ut if you tell them the why, they can decide here if they care enough to follow up.

Instead of linking on the word "filters", I'd recommend adding a sentence to the end of the section that says, "For more information, see [Filtering the OpenAPI tree elements].

View API documentation

• This section is also really thin. I think you should introduce the UI and explain the difference in obtaining the "raw" document vs the ui, per Martin's comment.

Also for the example URL, it shouldn't be hyperlinked to "endpoint"- because it doesn't resolve to anything. I was suggesting to provide that example for how a user might construct their own URL. Like:

"You can view the API documents by pointing your browser to the endpoint URL, for example http://localhost:9443/openapi/ui, where where localhost is your hostname and 9443 is the port number for your application. "

That is consistent with how we have demonstrated endpoint URLs elsewhere in the OL docs but verify with the SME that it is a viable example in this case.

• Some deprecated annotations were removed between 1.1 and 2.0 resulting in potential breaking changes. For more information, see Release Notes for Microprofile OpenAPI 2.0

--->
Some deprecated annotations were removed between Microprofile OpenAPI versions 1.1 and 2.0, which might result in breaking changes between those versions. For more information, see the Release Notes for Microprofile OpenAPI 2.0

[ManasiGandhi]

@dmuelle I worked on the filters section of the MP OpenAPI doc. I looked up the spec and the filters do apply to the static files.

[dmuelle]

Hi Manasi- doc looks good! Just a couple minor Acrolinx issues to address:

• replace both instances of "tree map" with "treemap"
• YAML-->yaml throughout
• In order to---> To
• all other documentation mechanisms have completed--->all other documentation mechanisms are finished

[dmuelle]

changes look good, signing off

[ManasiGandhi]

@rw2513 Can you peer review https://draft-openlibertyio.mybluemix.net/docs/21.0.0.3/documentation-openapi.html?

[Rwalls1]

Peer review

The topic looks good, I just have a few comments:

Introduction

• I think the phrase “write an application that communicates” could be a bit confusing as I’m not sure what the word “write” means in this context. I think you should change the phrase to “make applications that communicate” to avoid any possible confusion
• I think the phrase "without the need to access the source code” is also a bit confusing as it doesn’t seem completely clear what “without the need” is referring to. I think may be referring to the notion that developers wouldn’t need to access the source code, so to make that clearer I think you should change that phrase to “that doesn’t require access to the source code.” to make that distinction clearer.
• I don’t think the sentence that starts with “Therefore, developers don’t need” adds much value. I think it is already implied that if the documentation is generated from the source that a developer won’t have to create documentation about information that is already included in the generated doc based from the code. Also, since the following sentence that starts with “The reference document” references what the generated document includes, I think you could remove that sentence without losing clarity.
• For the phrase, “generate the stubs”, I think you should add a sentence or two that clarifies what stubs are to avoid confusion.
• In the last paragraph, the reference to the audience switches between "developers" and "you" or "your". I think you should maintain a consistent reference to the audience throughout, which I think should be "you" or "your" to maintain consistency across topics

The code-first approach

• Typo: Change "JAX-RS method purchaseCar().” to “purchaseCar() JAX-RS method"
• I think rather than saying “generated from the example”, I think you should specify the action so that the purpose of the related example is clearer, so maybe change that phrase to something like “generated after the OpenAPI annotations are added” to maintain clarity.
• Also, I think you should revise the syntax of the sentence, "See the MicroProfile OpenAPI Javadoc for the annotations that are available.” to be consistent with the syntax that is used to refer to links throughout the rest of the topic, such as “For more information, see”.

The design-first approach

• The sentence that starts with “In large companies” doesn’t seem to add any value without additional context as it doesn’t seem to mesh well with the rest of the paragraph. Also, the phrase “subject matter experts” seems a bit confusing in terms of perspective because the established audience seems to be developers who in most cases would be the subject matter experts so I think this sentence could also be removed.
• For the phrase, “then forms a contract and must be implemented as agreed”, I think you should add a sentence or two that explains what “contract” means in this context to add more meaning.

Filter components in and out of API documentation

• The phrases, “called one time” and “calls your implementation” don’t make sense to me without additional context. How does the call work? For the phrase, “called one time” I think you should explain what calls the filter. So, a bit more explanation about the call function would be useful. I don’t think this point explained in the guide that is linked to either so I think it should be covered.
• For the sentence, "With filters, you can implement an interface in your application.”, I think you add a sentence for phrase afterwards that explains why implementing an interface is important or how/why it is useful, such as "With filters, you can implement an interface in your application to add more structure”

View API documentation

• I think there needs to be more context added to the phrase “in the UI” as it’s not clear what UI is being referred to, so maybe change to something like “in the UI of the application.
• The phrase “point a browser at” seems a bit ambiguous so I think you should use a more precise wording such as “use a browser to go to"

[ManasiGandhi]

@rw2513 Hi Richard. I worked on your peer review. https://draft-openlibertyio.mybluemix.net/docs/21.0.0.3/documentation-openapi.html

• I think the phrase “write an application that communicates” could be a bit confusing as I’m not sure what the word “write” means in this context. I think you should change the phrase to “make applications that communicate” to avoid any possible confusion
• I think the phrase "without the need to access the source code” is also a bit confusing as it doesn’t seem completely clear what “without the need” is referring to. I think may be referring to the notion that developers wouldn’t need to access the source code, so to make that clearer I think you should change that phrase to “that doesn’t require access to the source code.” to make that distinction clearer.
• I don’t think the sentence that starts with “Therefore, developers don’t need” adds much value. I think it is already implied that if the documentation is generated from the source that a developer won’t have to create documentation about information that is already included in the generated doc based from the code. Also, since the following sentence that starts with “The reference document” references what the generated document includes, I think you could remove that sentence without losing clarity.
• For the phrase, “generate the stubs”, I think you should add a sentence or two that clarifies what stubs are to avoid confusion.
• In the last paragraph, the reference to the audience switches between "developers" and "you" or "your". I think you should maintain a consistent reference to the audience throughout, which I think should be "you" or "your" to maintain consistency across topics.- "Developers" in the topic refers to other developers, while "you", "your" refers to you as a developer.
• Typo: Change "JAX-RS method purchaseCar().” to “purchaseCar() JAX-RS method"
• I think rather than saying “generated from the example”, I think you should specify the action so that the purpose of the related example is clearer, so maybe change that phrase to something like “generated after the OpenAPI annotations are added” to maintain clarity.
• Also, I think you should revise the syntax of the sentence, "See the MicroProfile OpenAPI Javadoc for the annotations that are available.” to be consistent with the syntax that is used to refer to links throughout the rest of the topic, such as “For more information, see”.
• The sentence that starts with “In large companies” doesn’t seem to add any value without additional context as it doesn’t seem to mesh well with the rest of the paragraph. Also, the phrase “subject matter experts” seems a bit confusing in terms of perspective because the established audience seems to be developers who in most cases would be the subject matter experts so I think this sentence could also be removed.- “In large companies” refers to common a use case scenario where “subject matter experts” are not only the developers but other decision makers in administration etc.
• For the phrase, “then forms a contract and must be implemented as agreed”, I think you should add a sentence or two that explains what “contract” means in this context to add more meaning.- This refers to the scenario where an OpenAPI document is written in advance and forms a contract to abide by.
• The phrases, “called one time” and “calls your implementation” don’t make sense to me without additional context. How does the call work? For the phrase, “called one time” I think you should explain what calls the filter. So, a bit more explanation about the call function would be useful. I don’t think this point explained in the guide that is linked to either so I think it should be covered.- the previous SME said that the filters section is an advanced use case, and to document some information and link to the guide.
• For the sentence, "With filters, you can implement an interface in your application.”, I think you add a sentence for phrase afterwards that explains why implementing an interface is important or how/why it is useful, such as "With filters, you can implement an interface in your application to add more structure”-same as above. I'm not sure if filtering adds more structure or gives the ability to customize.
• I think there needs to be more context added to the phrase “in the UI” as it’s not clear what UI is being referred to, so maybe change to something like “in the UI of the application.
• The phrase “point a browser at” seems a bit ambiguous so I think you should use a more precise wording such as “use a browser to go to"

[Rwalls1]

@ManasiGandhi Thanks, your updates look good.

[ManasiGandhi]

https://staging-openlibertyio.mybluemix.net/docs/21.0.0.3/documentation-openapi.html

[dmuelle]

https://openliberty.io/docs/latest/documentation-openapi.html