如何写swagger接口文档

  1 openapi: 3.0.3
  2 info:
  3   title: Swagger Petstore - OpenAPI 3.0
  4   description: |-
  5     This is a sample Pet Store Server based on the OpenAPI 3.0 specification.  You can find out more about
  6     Swagger at [https://swagger.io](https://swagger.io). In the third iteration of the pet store, we've switched to the design first approach!
  7     You can now help us improve the API whether it's by making changes to the definition itself or to the code.
  8     That way, with time, we can improve the API in general, and expose some of the new features in OAS3.
  9 
 10     _If you're looking for the Swagger 2.0/OAS 2.0 version of Petstore, then click [here](https://editor.swagger.io/?url=https://petstore.swagger.io/v2/swagger.yaml). Alternatively, you can load via the `Edit > Load Petstore OAS 2.0` menu option!_
 11     
 12     Some useful links:
 13     - [The Pet Store repository](https://github.com/swagger-api/swagger-petstore)
 14     - [The source API definition for the Pet Store](https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml)
 15   termsOfService: http://swagger.io/terms/
 16   contact:
 17     email: apiteam@swagger.io
 18   license:
 19     name: Apache 2.0
 20     url: http://www.apache.org/licenses/LICENSE-2.0.html
 21   version: 1.0.11
 22 externalDocs:
 23   description: Find out more about Swagger
 24   url: http://swagger.io
 25 servers:
 26   - url: https://petstore3.swagger.io/api/v3
 27 tags:
 28   - name: pet
 29     description: Everything about your Pets
 30     externalDocs:
 31       description: Find out more
 32       url: http://swagger.io
 33   - name: store
 34     description: Access to Petstore orders
 35     externalDocs:
 36       description: Find out more about our store
 37       url: http://swagger.io
 38   - name: user
 39     description: Operations about user
 40 paths:
 41   /pet:
 42     put:
 43       tags:
 44         - pet
 45       summary: Update an existing pet
 46       description: Update an existing pet by Id
 47       operationId: updatePet
 48       requestBody:
 49         description: Update an existent pet in the store
 50         content:
 51           application/json:
 52             schema:
 53               $ref: '#/components/schemas/Pet'
 54           application/xml:
 55             schema:
 56               $ref: '#/components/schemas/Pet'
 57           application/x-www-form-urlencoded:
 58             schema:
 59               $ref: '#/components/schemas/Pet'
 60         required: true
 61       responses:
 62         '200':
 63           description: Successful operation
 64           content:
 65             application/json:
 66               schema:
 67                 $ref: '#/components/schemas/Pet'          
 68             application/xml:
 69               schema:
 70                 $ref: '#/components/schemas/Pet'
 71         '400':
 72           description: Invalid ID supplied
 73         '404':
 74           description: Pet not found
 75         '405':
 76           description: Validation exception
 77       security:
 78         - petstore_auth:
 79             - write:pets
 80             - read:pets
 81     post:
 82       tags:
 83         - pet
 84       summary: Add a new pet to the store
 85       description: Add a new pet to the store
 86       operationId: addPet
 87       requestBody:
 88         description: Create a new pet in the store
 89         content:
 90           application/json:
 91             schema:
 92               $ref: '#/components/schemas/Pet'
 93           application/xml:
 94             schema:
 95               $ref: '#/components/schemas/Pet'
 96           application/x-www-form-urlencoded:
 97             schema:
 98               $ref: '#/components/schemas/Pet'
 99         required: true
100       responses:
101         '200':
102           description: Successful operation
103           content:
104             application/json:
105               schema:
106                 $ref: '#/components/schemas/Pet'          
107             application/xml:
108               schema:
109                 $ref: '#/components/schemas/Pet'
110         '405':
111           description: Invalid input
112       security:
113         - petstore_auth:
114             - write:pets
115             - read:pets
116   /pet/findByStatus:
117     get:
118       tags:
119         - pet
120       summary: Finds Pets by status
121       description: Multiple status values can be provided with comma separated strings
122       operationId: findPetsByStatus
123       parameters:
124         - name: status
125           in: query
126           description: Status values that need to be considered for filter
127           required: false
128           explode: true
129           schema:
130             type: string
131             default: available
132             enum:
133               - available
134               - pending
135               - sold
136       responses:
137         '200':
138           description: successful operation
139           content:
140             application/json:
141               schema:
142                 type: array
143                 items:
144                   $ref: '#/components/schemas/Pet'          
145             application/xml:
146               schema:
147                 type: array
148                 items:
149                   $ref: '#/components/schemas/Pet'
150         '400':
151           description: Invalid status value
152       security:
153         - petstore_auth:
154             - write:pets
155             - read:pets
156   /pet/findByTags:
157     get:
158       tags:
159         - pet
160       summary: Finds Pets by tags
161       description: Multiple tags can be provided with comma separated strings. Use tag1, tag2, tag3 for testing.
162       operationId: findPetsByTags
163       parameters:
164         - name: tags
165           in: query
166           description: Tags to filter by
167           required: false
168           explode: true
169           schema:
170             type: array
171             items:
172               type: string
173       responses:
174         '200':
175           description: successful operation
176           content:
177             application/json:
178               schema:
179                 type: array
180                 items:
181                   $ref: '#/components/schemas/Pet'          
182             application/xml:
183               schema:
184                 type: array
185                 items:
186                   $ref: '#/components/schemas/Pet'
187         '400':
188           description: Invalid tag value
189       security:
190         - petstore_auth:
191             - write:pets
192             - read:pets
193   /pet/{petId}:
194     get:
195       tags:
196         - pet
197       summary: Find pet by ID
198       description: Returns a single pet
199       operationId: getPetById
200       parameters:
201         - name: petId
202           in: path
203           description: ID of pet to return
204           required: true
205           schema:
206             type: integer
207             format: int64
208       responses:
209         '200':
210           description: successful operation
211           content:
212             application/json:
213               schema:
214                 $ref: '#/components/schemas/Pet'          
215             application/xml:
216               schema:
217                 $ref: '#/components/schemas/Pet'
218         '400':
219           description: Invalid ID supplied
220         '404':
221           description: Pet not found
222       security:
223         - api_key: []
224         - petstore_auth:
225             - write:pets
226             - read:pets
227     post:
228       tags:
229         - pet
230       summary: Updates a pet in the store with form data
231       description: ''
232       operationId: updatePetWithForm
233       parameters:
234         - name: petId
235           in: path
236           description: ID of pet that needs to be updated
237           required: true
238           schema:
239             type: integer
240             format: int64
241         - name: name
242           in: query
243           description: Name of pet that needs to be updated
244           schema:
245             type: string
246         - name: status
247           in: query
248           description: Status of pet that needs to be updated
249           schema:
250             type: string
251       responses:
252         '405':
253           description: Invalid input
254       security:
255         - petstore_auth:
256             - write:pets
257             - read:pets
258     delete:
259       tags:
260         - pet
261       summary: Deletes a pet
262       description: delete a pet
263       operationId: deletePet
264       parameters:
265         - name: api_key
266           in: header
267           description: ''
268           required: false
269           schema:
270             type: string
271         - name: petId
272           in: path
273           description: Pet id to delete
274           required: true
275           schema:
276             type: integer
277             format: int64
278       responses:
279         '400':
280           description: Invalid pet value
281       security:
282         - petstore_auth:
283             - write:pets
284             - read:pets
285   /pet/{petId}/uploadImage:
286     post:
287       tags:
288         - pet
289       summary: uploads an image
290       description: ''
291       operationId: uploadFile
292       parameters:
293         - name: petId
294           in: path
295           description: ID of pet to update
296           required: true
297           schema:
298             type: integer
299             format: int64
300         - name: additionalMetadata
301           in: query
302           description: Additional Metadata
303           required: false
304           schema:
305             type: string
306       requestBody:
307         content:
308           application/octet-stream:
309             schema:
310               type: string
311               format: binary
312       responses:
313         '200':
314           description: successful operation
315           content:
316             application/json:
317               schema:
318                 $ref: '#/components/schemas/ApiResponse'
319       security:
320         - petstore_auth:
321             - write:pets
322             - read:pets
323   /store/inventory:
324     get:
325       tags:
326         - store
327       summary: Returns pet inventories by status
328       description: Returns a map of status codes to quantities
329       operationId: getInventory
330       responses:
331         '200':
332           description: successful operation
333           content:
334             application/json:
335               schema:
336                 type: object
337                 additionalProperties:
338                   type: integer
339                   format: int32
340       security:
341         - api_key: []
342   /store/order:
343     post:
344       tags:
345         - store
346       summary: Place an order for a pet
347       description: Place a new order in the store
348       operationId: placeOrder
349       requestBody:
350         content:
351           application/json:
352             schema:
353               $ref: '#/components/schemas/Order'
354           application/xml:
355             schema:
356               $ref: '#/components/schemas/Order'
357           application/x-www-form-urlencoded:
358             schema:
359               $ref: '#/components/schemas/Order'
360       responses:
361         '200':
362           description: successful operation
363           content:
364             application/json:
365               schema:
366                 $ref: '#/components/schemas/Order'
367         '405':
368           description: Invalid input
369   /store/order/{orderId}:
370     get:
371       tags:
372         - store
373       summary: Find purchase order by ID
374       description: For valid response try integer IDs with value <= 5 or > 10. Other values will generate exceptions.
375       operationId: getOrderById
376       parameters:
377         - name: orderId
378           in: path
379           description: ID of order that needs to be fetched
380           required: true
381           schema:
382             type: integer
383             format: int64
384       responses:
385         '200':
386           description: successful operation
387           content:
388             application/json:
389               schema:
390                 $ref: '#/components/schemas/Order'          
391             application/xml:
392               schema:
393                 $ref: '#/components/schemas/Order'
394         '400':
395           description: Invalid ID supplied
396         '404':
397           description: Order not found
398     delete:
399       tags:
400         - store
401       summary: Delete purchase order by ID
402       description: For valid response try integer IDs with value < 1000. Anything above 1000 or nonintegers will generate API errors
403       operationId: deleteOrder
404       parameters:
405         - name: orderId
406           in: path
407           description: ID of the order that needs to be deleted
408           required: true
409           schema:
410             type: integer
411             format: int64
412       responses:
413         '400':
414           description: Invalid ID supplied
415         '404':
416           description: Order not found
417   /user:
418     post:
419       tags:
420         - user
421       summary: Create user
422       description: This can only be done by the logged in user.
423       operationId: createUser
424       requestBody:
425         description: Created user object
426         content:
427           application/json:
428             schema:
429               $ref: '#/components/schemas/User'
430           application/xml:
431             schema:
432               $ref: '#/components/schemas/User'
433           application/x-www-form-urlencoded:
434             schema:
435               $ref: '#/components/schemas/User'
436       responses:
437         default:
438           description: successful operation
439           content:
440             application/json:
441               schema:
442                 $ref: '#/components/schemas/User'
443             application/xml:
444               schema:
445                 $ref: '#/components/schemas/User'
446   /user/createWithList:
447     post:
448       tags:
449         - user
450       summary: Creates list of users with given input array
451       description: Creates list of users with given input array
452       operationId: createUsersWithListInput
453       requestBody:
454         content:
455           application/json:
456             schema:
457               type: array
458               items:
459                 $ref: '#/components/schemas/User'
460       responses:
461         '200':
462           description: Successful operation
463           content:
464             application/json:
465               schema:
466                 $ref: '#/components/schemas/User'          
467             application/xml:
468               schema:
469                 $ref: '#/components/schemas/User'
470         default:
471           description: successful operation
472   /user/login:
473     get:
474       tags:
475         - user
476       summary: Logs user into the system
477       description: ''
478       operationId: loginUser
479       parameters:
480         - name: username
481           in: query
482           description: The user name for login
483           required: false
484           schema:
485             type: string
486         - name: password
487           in: query
488           description: The password for login in clear text
489           required: false
490           schema:
491             type: string
492       responses:
493         '200':
494           description: successful operation
495           headers:
496             X-Rate-Limit:
497               description: calls per hour allowed by the user
498               schema:
499                 type: integer
500                 format: int32
501             X-Expires-After:
502               description: date in UTC when token expires
503               schema:
504                 type: string
505                 format: date-time
506           content:
507             application/xml:
508               schema:
509                 type: string
510             application/json:
511               schema:
512                 type: string
513         '400':
514           description: Invalid username/password supplied
515   /user/logout:
516     get:
517       tags:
518         - user
519       summary: Logs out current logged in user session
520       description: ''
521       operationId: logoutUser
522       parameters: []
523       responses:
524         default:
525           description: successful operation
526   /user/{username}:
527     get:
528       tags:
529         - user
530       summary: Get user by user name
531       description: ''
532       operationId: getUserByName
533       parameters:
534         - name: username
535           in: path
536           description: 'The name that needs to be fetched. Use user1 for testing. '
537           required: true
538           schema:
539             type: string
540       responses:
541         '200':
542           description: successful operation
543           content:
544             application/json:
545               schema:
546                 $ref: '#/components/schemas/User'          
547             application/xml:
548               schema:
549                 $ref: '#/components/schemas/User'
550         '400':
551           description: Invalid username supplied
552         '404':
553           description: User not found
554     put:
555       tags:
556         - user
557       summary: Update user
558       description: This can only be done by the logged in user.
559       operationId: updateUser
560       parameters:
561         - name: username
562           in: path
563           description: name that need to be deleted
564           required: true
565           schema:
566             type: string
567       requestBody:
568         description: Update an existent user in the store
569         content:
570           application/json:
571             schema:
572               $ref: '#/components/schemas/User'
573           application/xml:
574             schema:
575               $ref: '#/components/schemas/User'
576           application/x-www-form-urlencoded:
577             schema:
578               $ref: '#/components/schemas/User'
579       responses:
580         default:
581           description: successful operation
582     delete:
583       tags:
584         - user
585       summary: Delete user
586       description: This can only be done by the logged in user.
587       operationId: deleteUser
588       parameters:
589         - name: username
590           in: path
591           description: The name that needs to be deleted
592           required: true
593           schema:
594             type: string
595       responses:
596         '400':
597           description: Invalid username supplied
598         '404':
599           description: User not found
600 components:
601   schemas:
602     Order:
603       type: object
604       properties:
605         id:
606           type: integer
607           format: int64
608           example: 10
609         petId:
610           type: integer
611           format: int64
612           example: 198772
613         quantity:
614           type: integer
615           format: int32
616           example: 7
617         shipDate:
618           type: string
619           format: date-time
620         status:
621           type: string
622           description: Order Status
623           example: approved
624           enum:
625             - placed
626             - approved
627             - delivered
628         complete:
629           type: boolean
630       xml:
631         name: order
632     Customer:
633       type: object
634       properties:
635         id:
636           type: integer
637           format: int64
638           example: 100000
639         username:
640           type: string
641           example: fehguy
642         address:
643           type: array
644           xml:
645             name: addresses
646             wrapped: true
647           items:
648             $ref: '#/components/schemas/Address'
649       xml:
650         name: customer
651     Address:
652       type: object
653       properties:
654         street:
655           type: string
656           example: 437 Lytton
657         city:
658           type: string
659           example: Palo Alto
660         state:
661           type: string
662           example: CA
663         zip:
664           type: string
665           example: '94301'
666       xml:
667         name: address
668     Category:
669       type: object
670       properties:
671         id:
672           type: integer
673           format: int64
674           example: 1
675         name:
676           type: string
677           example: Dogs
678       xml:
679         name: category
680     User:
681       type: object
682       properties:
683         id:
684           type: integer
685           format: int64
686           example: 10
687         username:
688           type: string
689           example: theUser
690         firstName:
691           type: string
692           example: John
693         lastName:
694           type: string
695           example: James
696         email:
697           type: string
698           example: john@email.com
699         password:
700           type: string
701           example: '12345'
702         phone:
703           type: string
704           example: '12345'
705         userStatus:
706           type: integer
707           description: User Status
708           format: int32
709           example: 1
710       xml:
711         name: user
712     Tag:
713       type: object
714       properties:
715         id:
716           type: integer
717           format: int64
718         name:
719           type: string
720       xml:
721         name: tag
722     Pet:
723       required:
724         - name
725         - photoUrls
726       type: object
727       properties:
728         id:
729           type: integer
730           format: int64
731           example: 10
732         name:
733           type: string
734           example: doggie
735         category:
736           $ref: '#/components/schemas/Category'
737         photoUrls:
738           type: array
739           xml:
740             wrapped: true
741           items:
742             type: string
743             xml:
744               name: photoUrl
745         tags:
746           type: array
747           xml:
748             wrapped: true
749           items:
750             $ref: '#/components/schemas/Tag'
751         status:
752           type: string
753           description: pet status in the store
754           enum:
755             - available
756             - pending
757             - sold
758       xml:
759         name: pet
760     ApiResponse:
761       type: object
762       properties:
763         code:
764           type: integer
765           format: int32
766         type:
767           type: string
768         message:
769           type: string
770       xml:
771         name: '##default'
772   requestBodies:
773     Pet:
774       description: Pet object that needs to be added to the store
775       content:
776         application/json:
777           schema:
778             $ref: '#/components/schemas/Pet'
779         application/xml:
780           schema:
781             $ref: '#/components/schemas/Pet'
782     UserArray:
783       description: List of user object
784       content:
785         application/json:
786           schema:
787             type: array
788             items:
789               $ref: '#/components/schemas/User'
790   securitySchemes:
791     petstore_auth:
792       type: oauth2
793       flows:
794         implicit:
795           authorizationUrl: https://petstore3.swagger.io/oauth/authorize
796           scopes:
797             write:pets: modify pets in your account
798             read:pets: read your pets
799     api_key:
800       type: apiKey
801       name: api_key
802       in: header