3 minutes to master DITA structured writing situation published Swagger API document Swagger Endpoint sample sample DITA output prerequisite usage related reading

Because I recently received multiple questions about API documentation development, today I share with you how to publish Swagger API documentation under DITA structured writing conditions.

This article is intended for engineers and supervisors who have already invested in DITA and have swagger API documentation development needs to read and master.

<h1 class="pgc-h-arrow-right" data-track="5" > sample of Swagger Endpoint</h1>

"paths": {

"/pet": {

"put": {

"tags": [ "pet" ],

"summary": "Update an existing pet",

"description": "",

"operationId": "updatePet",

"consumes": ["application/json", "application/xml"],

"produces": ["application/xml", "application/json"],

"parameters": [

{

"in": "body", "name": "body", "required": true,

"description": "Pet object that needs to be added to the store",

"schema": { "$ref": "#/definitions/Pet" }

}

],

"responses": {

"400": {"description": "Invalid ID supplied"},

"404": {"description": "Pet not found"},

"405": {"description": "Validation exception"}

},

"security": [

"petstore_auth": ["write:pets","read:pets"]

]

<h1 class="pgc-h-arrow-right" data-track="3" > example DITA output</h1>

< h1 class="pgc-h-arrow-right" data-track="44" prerequisites ></h1>

Use our company's DITA OT Swagger plugin and install it. If you are interested, please contact us.

<h1 class="pgc-h-arrow-right" data-track="34" > usage</h1>

For DITA processing, swagger files can be defined as json or yaml format. If you mark a file that is processed by Swagger, ditamap as follows, with the tag format="swagger":

The attached file will be converted to a *.dita file and will be added to the build job without further processing. Unless overwritten, the navtitle contains a subject that will be the same as the root name of the file. Any underscores in the file name will be replaced by spaces in the header.

<h1 class="pgc-h-arrow-right" data-track="40" > related reading</h1>

What to use to write API documentation