Navigation
- 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 .
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 ？
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 :
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 .
