当前位置:网站首页>Lazy to write a document, swagger document does not smell

Lazy to write a document, swagger document does not smell

2020-11-09 12:55:35 Rong's life

  • Preface
  • Offline documents
    • 1 Save as html
    • 2 Export to pdf file
    • 3 Export to Word file
  • Reference resources

Preface

   I once wrote an article earlier 《 R & D team , Please take care of your API file 》. In teamwork , The importance of development documentation , No more details here , Today's topic focuses on how to further improve the use of documents more efficiently .

Offline documents

  swagger It's already very convenient , Why do we still need offline documentation ? The company has the same project team , Generally, as long as you integrate swagger Basically enough , But there are bound to be cross groups , There will even be projects for companies to cooperate with other countries . Especially in " Today when micro service is popular ", Between multiple teams , Because the division of labor is different , Authority is different , Often can't access each other's projects swagger file , There are several common practices :

  • Build a unified interface document management system

    Each project team has to manually write its own interface and archive it here , Need to view , Pull people into the organization to see .

  • Code is documentation

    Provide source code . The same project developer . That's what a lot of small companies do . No documents , Only the source code .

  • Offline documents
    Export the document to excel,docx,html The form such as , External output , For example, call to a third party .

   This article will focus on how to swaggerUI Export offline documents .

   The author tries the following three ways .

1 Save as html

Web Developers know that , As long as it is a web page, you can save it as a static web page .

 Use scenarios

then , Right click on Google browser to open

 Use scenarios

When I run my code , It's wrong :

swagger-ui-bundle.js:6 Fetch API cannot load file:///C:/swagger/v1/swagger.json. URL scheme must be "http" or "https" for CORS request.

   Obviously and swagger.json It matters , It's okay. Yeah swagger Know something about . Decisively by visiting http://localhost:5000/swagger/v1/swagger.json download swagger.json, And put it in the designated position .

 Use scenarios

   Run again , Error reporting is the same as before . This is a cross source resource sharing problem .
There are two ways to deal with it :

  • Using web servers .

    To be static html/js File runs a simple Web The server .

  • Change your chrome Launch parameters , And let it know that you want to ignore this security feature .

For details, please refer to :https://www.codenong.com/50445639/

What I'm using here is IIS The server , take js and html Deployed together in IIS On , as follows :

  • Change your chrome Launch parameters , And let it know that you want to ignore this security feature .

 Use scenarios

   After deployment , By deploying IP Address to access (PS: This is more suitable for the company , For example, it's time to separate the front end and the back end ).

2 Export to pdf file

This is simpler , Don't write code . utilize windows Its own function can be realized .

Click the shortcut key Ctrl+p, Display the printed page

 Use scenarios

Save it .

3 Export to Word file

   Of course , Although the above two methods are already very convenient . But sometimes , Come across some difficult , It's unreasonable , I just feel that I will Swagger It's not formal to leave the document address to the customer ! I want a share of life and death word file .

   But this time , If there are hundreds of interfaces , Even more , One by one manual input word, It's going to be a time-consuming job . But what can be done about it ?

   by the way , utilize Swagge Generated Json The file is converted to word Don't you think the document is OK ?

Realization way
  • obtain Swagger Interface document Json file

  • analysis Json File data is filled to Html In the form

  • According to the generated html turn work file

   This needs to be done in swagger Do some extensions in the document code . For details, please refer to : be based on .NetCore3.1 series —— Use Swagger Export document

   export word The format is as follows :

 Use scenarios

be based on swagger Generated document data , We can generate custom format data according to our own ideas . Interested children's shoes can continue to dig deep .

Reference resources

版权声明
本文为[Rong's life]所创,转载请带上原文链接,感谢