russell / fairy-slipper Goto Github PK

• Possibly re-design the table (currently in wadl) and remove the list from the table.
  • Create a separate list element.
• Verify that the generated rst is correct for an embedded list in table.
• Verify that markdown can handle a list embedded in table cell.
• An example can be found in ch_identity-v3.xml.

Hello.
When I try to run migrate.sh it fails with AssertionError and KeyError.
Here's the log:
http://paste.openstack.org/show/DVVdnMsayg16FFZ8tOQ8/

The object storage method, createContainer, has a method that returns a response with status codes 201 and 204 and this results in an error setting the response header params. Update the processing of multiple status codes per response.

Currently in the navigation extensions are listed as a separate section,

The extensions should be listed under the version e.g.

Compute
- v2.0
-- Exensions
- v2.1
-- Extensions

Lists with sub lists are not formatted correctly (missing a level of indentation).

I have to manually source the .venv/bin/activate file to get a virtual environment for the migrate.sh script. I'm not sure why my script never seems to use the /tools/with_venv.sh to source the bin/activate file?

Add an array of 'required' property names in definition of operation. Remove required fields in each property.
For example,
"createTags-v2": {
"required": [
"name", "namespace", "tags"
],
"properties": {
"name": {}
...
}

Add swagger tags to the JSON output of server.

We need to start developing javascript tests. So we need infra to support that and some initial tests.

I logged four bugs against api-site DocBook and WADL files. Two issues have been merged.
I am still looking into the remaining bugs. There are a few more to log. This should help clean-up the warnings from migrate.sh as well as tidy up the xml and wadl content.

That view probably wont be used too much. It should still be maintained, but if i remove it from the navigation then it will bring us closer to a polished product.

Links are processed in wadl files. Adding processing of links to docbkx chapter files.

look at confirming that the conversion of the source to Swaggerish matches our custom Swagger Schema. So we will need to find a schema validator and write a test that migrates all the data and checks it validates.

It's working again, and documented. But it needs to convert the stubs to swagger format if it can't find any documentation. This resulting swagger can then be fed to the swagger_to_rst script to generate an initial service documentation.

I have been thinking about how we can document some of the calls that take multiple requests and responses.

The mime type spec can use a ; to indicate subsequent parameters are options. You often see these used to indicate that the encoding is utf8 but we could use it to uniquely identify. I was thinking that they could be used to identify groups of request/responses. This would help in this case you describe above and it would also help in the case of the action url.

e.g.
application/text;action_id=reboot could be used to group request/responses that we want to match back to a reboot VM example?

This way we can have multiple example request/responses without them getting mixed up.

To implement this we would need to extend the RST example specification so that we could include the action_id

Sometimes the left hand label overlaps the operation title. The title is on the next line instead
of next to the label. I see this occurring, in orchestration -> Templates -> Show resource schema.

This will bring it in line with the rest of the httpdomain extensions that is being used.

.. swagger:tag:: policies
:synopsis: Policies

Manages policies.

You can encode policy rule sets into a blob to be consumed byremote
services. To do so, set typeto application/jsonand specify
policy rules as JSON strings in a blob. For example:

Some code blocks are being rendered on one line, but they obviously should span a few.

Just wanted to note here that we discussed at the Summit to move this repo to use the Gerrit workflow. Let us know in this issue if you have any difficulties with that move. I think it makes sense to move so that projects will know about it and use it for the API docs.

Currently the swagger to WADL ignores link tags like

<link xlink:href="http://specs.openstack.org/">Filtering and Column Selection</link>

Seems that some of the swift APIs use the COPY method.

To provide an easy way to alter the embedded markup format in the swagger output. This will be another way to round trip the data from rst -> swagger -> rst without needing to modify a markdown parser.

This will make writing supporting bots easier.

At the moment we pretty print the results but we don't update the content length header, so the example is a bit invalid :(

Output in database-v1-swagger.json contains,
Notes- A user is granted all privileges

There is a title node before the itemizedList node and no new line to separate the title from the list.
The first element of the list is missing the bullet and indentation.

I see a lot of " Unfortunately this API operation is not fully documented." when there's not much more to say about a particular call. 😶 Heh. So should we just move that one-liner short description into that area?

I have started to do this already, so i thought i should make sure it's visible.

Basically it's trivial to modify tempest to log all requests/responses to a log file the output looks like

Request (FlavorsV2TestJSON:test_get_flavor): 200 GET http://192.168.122.201:8774/v2.1/6b45254f6f7c44a1b65ddb8218932226/flavors/1 0.117s
Request - Headers: {'Content-Type': 'application/json', 'Accept': 'application/json', 'X-Auth-Token': '<omitted>'}
        Body: None
    Response - Headers: {'status': '200', 'content-length': '430', 'content-location': 'http://192.168.122.201:8774/v2.1/6b45254f6f7c44a1b65ddb8218932226/flavors/1', 'x-compute-request-id': 'req-959a09e8-3628-419d-964a-1be4ca604232', 'vary': 'X-OpenStack-Nova-API-Version', 'connection': 'close', 'x-openstack-nova-api-version': '2.1', 'date': 'Sun, 13 Sep 2015 07:43:01 GMT', 'content-type': 'application/json'}
        Body: {"flavor": {"name": "m1.tiny", "links": [{"href": "http://192.168.122.201:8774/v2.1/6b45254f6f7c44a1b65ddb8218932226/flavors/1", "rel": "self"}, {"href": "http://192.168.122.201:8774/6b45254f6f7c44a1b65ddb8218932226/flavors/1", "rel": "bookmark"}], "ram": 512, "OS-FLV-DISABLED:disabled": false, "vcpus": 1, "swap": "", "os-flavor-access:is_public": true, "rxtx_factor": 1.0, "OS-FLV-EXT-DATA:ephemeral": 0, "disk": 1, "id": "1"}}

From here i plan to write a tool to parse this into a data structure, then i will be able to merge this raw data with the existing swagger examples.

I think that we should define a new http method type called abstract, It's purpose will be to define the generic values of return codes and headers/parameters/tags that are relevant to all calls that inherit from this abstract implementation.

.. http:_abstract_:: /

   :statuscode 200: Success

Each real method definition should be able to inherit from a single abstract method. The abstract methods should be able to inherit from each other and the order they are loaded will determine which ones take precedence.

.. http:get:: /
   :inherits: /

   List versions

The resulting method from this contrived example should be equivalent to

.. http:get:: /

   List versions
   :statuscode 200: Success

This should allow for a massive reduction as any common elements like, headers or path arguments, or common return status codes can be easily defined and will be expressed from a single location. Instead of duplicated throughout the documentation.

2015-08-24 15:31:29,382 [INFO ] [pecan.commands.serve][MainThread] "GET /doc/objectstorage/v1/ HTTP/1.1" 200 41807
:199: (ERROR/3) Error in "code-block" directive:
maximum 1 argument(s) allowed, 6 supplied.

.. code-block:: json
"OS-OAUTH1": {
"access_token_id": "cce0b8be7"
}

This could probably be done using http://getbootstrap.com/css/#basic-abbreviation

e.g. /v3//OS-PKI/revoked from the identity v3 api

Since that's up to the cloud provider to put an API on http or https transport protocol, no need to output that in our Swagger files.

The font size of the short description text is too small. The text also contains semantic markup,
i.e., RESCUE .

• Add the description string to the swagger response object. Use the operationId and response status code for the description.
• Add the schema object to the swagger response object
  • For methods that list response parameters, update schema object to refer to this schema
• Generate the responseschema tags for displaying the response schema, see #27.

• wadl_to_swagger generates a rst literal block within the method's request parameter description.
• swagger_to_rst needs to be updated to maintain the formatting of this code block.

i'm trying to follow the workflow described in the README, but the defaults don't seem to be available.

steps to reproduce:

1. clone new fairy-slipper repository
2. run ./migrate.sh -V

output is as follows:

$ ./migrate.sh -V
python: can't open file 'tools/install_venv.py': [Errno 2] No such file or directory
./migrate.sh: line 96: tools/with_venv.sh: No such file or directory
./migrate.sh: line 97: tools/with_venv.sh: No such file or directory
./migrate.sh: line 98: tools/with_venv.sh: No such file or directory

There needs to be a way to visualise JSON schema

The database wadl file in api-site, dbaas.wadl contains several tables. The file database-v1-swagger.json, generated by wadl_to_swagger contains the tables, but with extra header fields, such as "Field 1", "Field 2", "Field 3" in each table. See prettytable.py add_row() and its usage in depart_tr(), wadl_to_swagger.py.

Consider integrating with horizon, so host out of the normal horizon interface.

Pros

• access to a token
• access to a proxy that will allow us to call other services without CORS
• access to the service catalog

As an alternative to rendering narrative text formatted as rst, directly output descriptions as Markdown.

Occasionally, there is a space inserted after the hyphen in a word, probably due to text wrapping. Typically the word is formatted as a code literal.
Ex. manilla- share

Two issues:

• When two literals are back to back there need to be two spaces between them, for example:
  Some example text another text and then more text.
• Should remove space after literal if next char is punctuation (. ; :) such as:
  This is an example of ending literal.
  Or, This is a sample text: and some more.

The wadl files appear to have introduced a change in the area of para and programlisting elements.
As a result, the rst rendering is not correct. The rendering of literal blocks, code examples in lists will need to be revisited as well as how and where to display curl examples (possibly not in the main description for the operation). See objectstorage as an example.

I narrowed down a problem loading the page for a number of services that contain tables,
database v1, image v2, blockstorage v2, networking-extension v2, identity-extension v2.
Two problems:

1. There appears to be a problem with the method,
   default_visit(self, node) in rest.py
   This is called after the table is visited and the subsequent index is a string not an integer.
2. The tables in the various .rst files are correct, but the table nodes in rest.py are
   written as text not html tables. I added methods visit_table, depart_table verifying that the
   node contains the table as html.

Literal blocks in an itemized list are not rendering correctly. Evaluate processing of programlisting elements within a paragraph in an itemizedlist. The generated json from wadl is missing new lines after the double colon.

Some of the service method descriptions embed curl commands along with http responses. Would it be useful to pull these out of the description and create a directive to tag as, for example, http req/resp output. This text could be associated with a curl/http (cmd, code block) widget and used within the display, outside of the description.

In situations where there is no doc string at the moment extra whitespace is created. :( it would be better if in cases where there is no doc string that only one blank line was output.

https://github.com/russell/fairy-slipper-migration/blob/tempest-log/api_doc/compute/v2.1.rst#L108

None of our WADL definitions have any information about securityDefinitions so no need to output in the generated Swagger. For more info about the securityDefinitions object, see:
https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#securityDefinitionsObject

Create widget that can be exposed within normal narrative documentation

https://forgeapi.puppetlabs.com/

Most of the current documentation is using Sphinx, so creating a sphinx plugin to inject the widget is probably the best step forward.

The response schema isn't displayed.

It should probably be incorporated along side the examples.

I think we want a interface that associates the schemas for requests with the request examples and vice versa.