Support REST API

[chenkennt]

No description provided.

[vicancy]

It's now supported. docfx-seed adds 2 swagger files into the project https://github.com/docascode/docfx-seed/tree/master/restapi and the result looks like: http://docascode.github.io/docfx-seed/restapi/petstore.html

[vdecristofaro]

Hello @vicancy ,
I have created a swagger file by using NSwag tool. I have placed the json file inside a "restapi" folder and then added a toc.md as you have made in your example.

I am getting an exception when building the docs which says

Error: System.AggregateException: One or more errors occurred. ---> 
Newtonsoft.Json.JsonException: type is already defined in referenced object "#/definitions/XXXXXX".
   at Microsoft.DocAsCode.Build.RestApi.Swagger.Internals.SwaggerObjectConverter.WriteJson(JsonWriter writer, Object value, JsonSerializer serializer) in C:\Users\qinzhu\workspace\docfx-latest\src\Microsoft.DocAsCode.Build.RestApi\Swagger\Internals\SwaggerObjectConverter.cs:line 40

Any suggestion?

[vicancy]

@vdecristofaro
Is the swagger file contains such code block:

{
    "$ref": "#/definitions/XXXX",
    "type": "XX"
}

and inside #/definitions/XXXX it also contains key type?
Such case it throws exception.

[vdecristofaro]

@vicancy Right.

this is an extract of the generated swagger

    "cp/redeem": {
      "Put": {
        "tags": [],
        "operationId": "Coupon_RedeemCoupon",
        "parameters": [
          {
            "name": "model",
            "in": "body",
            "required": false,
            "schema": {
              "type": [
                "null",
                "object"
              ],
              "$ref": "#/definitions/CouponRedeemViewModel"
            }
          }
        ],
        "responses": {
          "200": {
            "schema": {
              "type": "file"
            }
          }
        }
      }
    },

How would you then advice to solve this problem. Is this an issue with docfx?

[vicancy]

why there is extra

              "type": [
                "null",
                "object"
              ],

inside schema? it is not valid. I would suggest remove that block.

[vdecristofaro]

Hello @vicancy as you can see in my referenced issue that has been solved and now generate exactly the code reported by the NSwag project owner. I have also updated the docfx to 1.9.3.
However I am still getting the same error .

Info: [Build Document]5 plug-in(s) loaded.
Info: [Build Document]Max parallelism is 8.
Info: [Build Document]Markdown engine is dfm
Info: Completed building documents in 1078,1519 milliseconds.
Info: Completed executing in 1239,7334 milliseconds.
Error: System.AggregateException: One or more errors occurred. ---> Newtonsoft.Json.JsonException: type is already defined in referenced object "#/definitions/XXXXX".

the generated code now is as follow

    "cp/redeem": {
      "Put": {
        "tags": [],
        "operationId": "Coupon_RedeemCoupon",
        "parameters": [
          {
            "name": "model",
            "in": "body",
            "required": false,
            "schema": {
              "oneOf": [
                {
                  "type": "null"
                },
                {
                  "$ref": "#/definitions/CouponOperationViewModel"
                }
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "schema": {
              "type": "file"
            }
          }
        }
      }
    },

Could you please tell me how did you generate your json sample?

Thank you!

[hellosnow]

@vdecristofaro could you provide the json file or github repo for us? I will investigate for you. Thanks.

[vdecristofaro]

Sure @hellosnow. Here is a simple file I am using as a sample. the file is generated by using NSwag tool which by using the WebApiToSwagger generator described here.

Thanks!

tmp_swagger.txt

[hellosnow]

@vdecristofaro , I checked your attached swagger json and found its schema is invalid. Could you work with NSwag tool to generate the valid swagger json file? I use http://bigstickcarpet.com/swagger-parser/www/index.html to validate the swagger file, for example "typeName", "enumNames" and "oneOf" is not valid.

Some valid swagger files example: http://petstore.swagger.io/v2/swagger.json
Swagger schema: http://swagger.io/specification/

[hellosnow]

We also have plan to validate the swagger schema #312

[vdecristofaro]

@hellosnow
First of all thank you for your answer.
This is getting very strange and I can't understand the way to solve this.
I have tried to pass a Swashbuckle generated json to the bigstickcarpet parser and it tells me that is invalid. More specifically it says: This API is valid, but it cannot be shown because it contains circular references
Also NSwag generated file is invalid as you have already seen. I am using NSwag however only for the purpose of generating different swagger for each controller.

Could you please advice which kind of swagger generator should I use to create my swagger file?

[hellosnow]

Hi @vdecristofaro ,

• For "circular references", as the validation tool hints, that's an invalid case and docfx doesn't support it. For example, if A's type is defined as B while B's type is defined as A, docfx could not resolve the real type.
• For NSwag generated invalid json, I suggest you to file some issue and see whether they can help you to address the root cause to lead to invalid swagger file? Is it code bug of NSwag or incorrect type reference definition in your client/server side?

Considering not sure which language you're using to write for the client/server side, here's the swagger official tools: http://swagger.io/tools/, could you check if there's any suitable for you?

[vdecristofaro]

Hi @hellosnow,
My project is an ASP.NET web api 2.2 project (.Net 4.6.1).
Let me give you a bit of reference on what I am doing

• I have integrated the Swashbuckle nuget package in the web api and I am really enjoying the swagger documentation generated. To create a much more detailed documentation for my API I am evaluating DocFX. Because DocFX require a single json for every API I have also filled an issue to Swashbuckle to ask if it is possible to generate a single json for every controller.
• Regarding NSwag. I have done exactly what you suggest here. The project owner told me that the problem seems to be related to the fact that Newtonsoft does not handle JSON Schema v4 as specified by the Swagger specification. You can follow the entire discussion here. As the NSwag project owner says in the issue I dont really understand why a path in the file get validated with the message Additional properties not allowed: cp/redeem,cp/create at #/paths.

Apart from this, I still do not understand where the circular reference would be. The Swashbuckle generated JSON is correctly handled by the swagger-ui package which shows the generated documentation. I really dont know how to proceed here.

[hellosnow]

@vdecristofaro I will look into the Swashbuckle and NSwag tomorrow carefully and give you update later. But I just did one testing on official swagger io and found it cannot be processed:

1. Open http://petstore.swagger.io/
2. Enter your swagger url: https://raw.githubusercontent.com/hellosnow/docfx-seed/issue181/restapi/tmp_swagger.json, which I just uploaded in my repo.
3. Click Explore.
4. Check error report at http://online.swagger.io/validator/debug?url=https://raw.githubusercontent.com/hellosnow/docfx-seed/issue181/restapi/tmp_swagger.json
5. the validation error is same with the one in http://bigstickcarpet.com/swagger-parser/www/index.html?

• Additional properties not allowed: cp/redeem,cp/create at #/paths.
• TypeName and EnumName

[RicoSuter]

In NSwag v2.43, the missing / prefix is added to the paths and the typeName and enumNames fields are prefixed with x- (custom fields). Now the generated Swagger spec should be valid...

[hellosnow]

Thanks @RSuter for the quick update. @vdecristofaro could you try to generate the new Swagger json file by NSwag v2.43? We can try to parse the new generated json file in docfx and see whether it works.

[vdecristofaro]

I did it. DocFX now still end with error during the build

Info: Completed building documents in 2208,5322 milliseconds.
Info: Completed executing in 3194,5989 milliseconds.
Error: System.AggregateException: One or more errors occurred. ---> Newtonsoft.Json.JsonException: type is already defined in referenced object "#/definitions/ReceiptProduct". at Microsoft.DocAsCode.Build.RestApi.Swagger.Internals.SwaggerObjectConverter.WriteJson(JsonWriter writer, Object value, JsonSerializer serializer)

I have tried to parse the resulting json at http://bigstickcarpet.com/swagger-parser/www/index.html and i get the following error

Swagger schema validation failed. 
  Additional properties not allowed: oneOf at #/definitions/Payment/properties/Method

JSON_OBJECT_VALIDATION_FAILED
```.

I am attaching the new json file here. Thanks for helping




[tmp_swagger.txt](https://github.com/dotnet/docfx/files/297244/tmp_swagger.txt)

[RicoSuter]

Ok, now the problem is probably that JSON.net just supports JSON Schema v3, but Swagger requires v4.
See link at bottom: https://github.com/json-schema/json-schema/wiki/anyOf,-allOf,-oneOf,-not
As I told, I implemented the whole Swagger object model + JSON Schema v4 in http://nswag.org (nuget: NSwag.Core)

[hellosnow]

Seems oneOf is not supported by swagger? Discussions are on Support oneOf: "Swagger use an extended subset of JSON Schema, and explicitly don't support oneOf", refer to Swagger schema definition

[RicoSuter]

Oh well, what a mess this Swagger is...

[RicoSuter]

Without oneOf you cannot express a nullable property which references another schema (which is not nullable)..

[vdecristofaro]

Well, at the least we clarified something.
Despite the fact that, as it seems to me, NSwag cannot be taken in account to generate swagger files, could you please provide an alternative which works with DocFX?

I have a project with more than one hundred api endpoints. How can I use DocFX to generate documentation? Do you suppose that swaggers have to be created manually?

[RicoSuter]

I'd like to support this/more scenarios but I need to know how to work around these issues:
See OAI/OpenAPI-Specification#333 (comment)

[hellosnow]

As far as I know, Swashbuckle is ok. @vdecristofaro I remember you used this tool to generate json filw right? Could you provide it to us to test whether it's valid Swagger file?

[vdecristofaro]

@hellosnow
Well I had the time to do some testing and got some results to share.

• I can confirm that Swashbuckle is ok. However there is a problem in using it and it is due to the fact that Swashbuckle only generates a single json file with all the endpoints and api exposed from my project. This behaviour has the side effect that docfx generate a single page documenting all the endpoints. In my scenario these endpoints are more than 100 and this produce a slow loading page with over 100 links on the right side menu. Moreover does not give me the chance to fully organize those endpoints in logical related categories by using features of the toc.md (left side menu). As you can see here I have already asked for help on generating a single json file for every API controller.
• With the help of @RSuter I am now able to generate a single file for every controller by using NSwag. The generated swaggers are fully validated here (please try yourself by using the attached swagger sample at the end of this message). However when using the NSwag generated files DocFX now raise the following error:

Error: System.AggregateException: One or more errors occurred. ---> Newtonsoft.Json.JsonSerializationException: Self referencing loop detected with type 'Microsoft.DocAsCode.Build.RestApi.Swagger.Internals.SwaggerObject'. Path ''.
   at Newtonsoft.Json.Serialization.JsonSerializerInternalWriter.CheckForCircularReference(JsonWriter writer, Object value, JsonProperty property, JsonContract contract, JsonContainerContract containerContract, JsonProperty containerProperty)

Could you please check why this error occur now?

Thank you.

tmp_swagger.txt

UPDATE: I have also found another issue, #223, wich has already been filed on the repository.

[hellosnow]

@vdecristofaro I tried to parse the attached json by docfx and it succeeded without error? Which docfx version are you using? Suggest to update to latest bits 2.0.1

I will continue to look into your json on the final formatting. Also I filed some known issue #358 #360 , and will look at #223 , thanks for pointing out.

[hellosnow]

Hello @vdecristofaro , how's everything going for rest swagger?

For loop reference issue, we have fixed via #453 and #464 .The code is already in dev branch, will release at July 18th.

Also, we support more syntax via #358, #359 and #360 .

Could you have a try for your project? Any further issues please let us know.

[vdecristofaro]

Great. I will tra to run afgani my test on this and feedback quickly.
Thanks for support

[vdecristofaro]

@hellosnow I had the chance to run all my test against the latest release and can confirm that the issue has been solved. the issue can be closed.
Thanks a lot for the collaboration and help!

[hellosnow]

@vdecristofaro glad to hear that, will close the issue now.