swagger入门

Swagger是一款开源的API文档生成工具，主要用于开发RESTful接口。它能够让我们以注释的方式来定义接口的文档，并且能够自动生成可读性很高的API文档和在线测试API。Swagger的出现极大地方便了前后端的开发者，使得接口的文档化变得更加自动化、标准化。 文档在软件开发的任何阶段都是非常重要的。没有文档，软件的可维护性就会大打折扣，进而影响到软件的可扩展性。最终，软件可能会演变成一团难以理解、难以维护的代码。对于不同系统之间的接口文档来说，其重要性更是不言而喻。 在传统的软件开发过程中，接口文档的编写常采用口口相传、使用Word或其他文本文件进行保存、用wiki编写文档的方式。然而这些方式都存在缺点，比如文档不易维护，测试接口时不方便，以及接口变更时文档未能同步更新等问题。 Swagger通过编写注释来编写文档的方式改变了这种状况。在Swagger中，编写文档的过程就相当于是在写代码，当接口代码发生变化时，文档能够非常方便地得到更新。Swagger还支持方便的接口测试功能，使开发者在编写文档的同时，也能同步测试接口。 要使用Swagger，首先需要在Springboot项目中添加Swagger的依赖。具体操作是在项目的pom.xml文件中加入springfox-swagger2和springfox-swagger-ui的依赖。版本选择的是2.7.0。 接下来需要编写一个controller作为API接口。例如，可以创建一个DemoController类，定义添加、删除和展示用户信息的接口。这些接口看起来和普通的controller没有什么区别。 为了让Swagger生成接口文档并且提供接口测试，还需要进行Swagger的配置，主要是在Springboot项目中创建SwaggerConfig类，并且加入@Configuration和@EnableSwagger2注解来启用Swagger。在SwaggerConfig类中，通过创建Docket对象并配置，可以指定API文档的生成范围，比如指定基础包、API的路径等。此外，还可以定义API的基本信息，比如标题、描述和版本。 配置完成后，通过启动Springboot应用，并访问 ***实际端口号根据本地配置进行更改)，开发者可以查看Swagger生成的界面，这里会展示API文档的页面，包括了各个Restful方法的详细文档信息。不过，初始页面上的文档比较基础，开发者需要添加相应的注释，以便Swagger能够根据注释生成更详细的接口文档信息。 通过Swagger，开发人员可以更好地维护文档与代码的同步更新，提高开发效率，降低因文档不一致带来的错误。同时，Swagger还支持在线测试接口，极大地方便了接口的调试和验证工作。Swagger的使用，为前后端分离的开发模式提供了强有力的支持。