- Offline documents
- 1 Save as html
- 2 Export to pdf file
- 3 Export to Word file
- Reference resources
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 .
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 .
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 .
then , Right click on Google browser to open
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 .
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 .
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
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 ？
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 :
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 .