Swagger教程

Swagger搭建Restful接口教程一

一、前言

       Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件，随着现在许多公司实现了前后端分离，swagger越来越受欢迎了。

中文官网：http://www.sosoapi.com/

二、历史版本（绝版干货）      

         其实swagger是有两个版本的，而且区别还挺大的，一个是swagger-ui也就是swagger1;还有一个是springfox-swagger也就是swagger2;很多人都不知道给搞混淆了，两个版本各有各得特色，本篇博客先说swagger-ui。

三、版本一（swagger-ui）

 

 

通过输入http://localhost:8080/项目跟路径/dist/index.html直接可以访问自己的页面。

我的是http://localhost:8080/swagger_springmvc/dist/index.html#/

四、准备工作

前端html下载

  下载dist文件

1. swagger-ui版本首先需下载HTML有两种方式
2. 第一种：从github上下载相关html  ,;

https://github.com/swagger-api/swagger-ui

 

 

 注意事项

如果采取第一种下载方式的话，一定要注意版本，千万不要下载最新的版本dist否则swagger-ui是不支持的。要下载2.x版本的。

详细地址：https://github.com/swagger-api/swagger-ui/tree/2.x/dist

个人建议还是从我的博客中下载吧，毕竟我已经都给弄好了。
Jar包下载

?

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17

<!-- Swagger包 -->             swagger-springmvc 1.0.2             swagger-models 1.0.2             swagger-annotations 1.3.11 <!-- JSON包 -->             json-lib 2.4 <!-- JACKSON包 -->             jackson-annotations 2.6.5             jackson-databind 2.6.5             jackson-core 2.6.5

 

 

 

 注意事项

       这些jar包的版本不能改变，如果版本改了很可能因为版本的原因而实现不了，说个最简单的Swagger jar包 版本如果变了，很大可能就不行，这个之前博主亲自试验过。

      如果你的项目是maven项目的话，那么给的建议就是将这些jar包配到自己的maven仓库。然后再pom文件里引入，就像我的这样。

 

当然你也可以直接add引入，个人建议还是放在pom里比较规范。

五、代码实现

jar包引入

        要引入的jar包（第三章）之前就说了。

前端dist文件引入

        将下载的dist文件拷贝到webapp目录下。(我用的是myeclipse,不同的软件名字可能不一样)

 

 

 在dist文件夹下的index.html文件中修改url将之修改成为你项目swagger的url url命名规范是 IP+端口号+项目根路径(如果你项目有根路径的话)+api-docs

注意事项

        url后的 api-docs是固定的

 

 

 

 

Config配置

新建config文件夹,在文件中新建swagger.java文件，配置启动相关信息。

 

 

 

 

 然后再配置文件中引入本文件

 

 

Controller注解

控制层可以有两种方式展现根据大家喜好来。

方式一

 

 方式二

 

 

两种方式都可以 看大家喜欢那种写法。

六、成果展现访问        

启动项目 访问地址

        地址是 IP + 端口号 +项目跟路径 + / dist/index.html#/

        我的是http://localhost:8080/swagger_springmvc/dist/index.html#/ 后缀是固定的 不要改变

 

 

 Swagger搭建Restful接口教程二

一、前言

        上一章节我们说的是swagger-ui也就是swagger1,接下来我们说的是swagger升级版swagger2

        Swagger是当前最好用的Restful API文档生成的开源项目,随着swagger的越来越流行，原来需要有人把dist封装成jar,与spring相关框架结合，也就成了springfox-swagger
二、历史版本（绝版干货）

    其实swagger是有两个版本的，而且区别还挺大的，一个是swagger-ui也就是swagger1;还有一个是springfox-swagger也就是swagger2;很多人都不知道给搞混淆了，两个版本各有各得特色，本章二说springfox-swagger。

三、版本二（springfox-swagger(swagger2)）

效果展示

 

 

 通过输入http://localhost:8080/项目跟路径/swagger-ui.html直接可以访问自己的页面。我的是http://localhost:8080/springfox_springmvc/swagger-ui.html

         因为页面是封装好的，所以后缀swagger-ui.html是不变的

三、准备工作

Jar包下载

<!-- Swagger包 -->

springfox-core-2.6.1

springfox-schema-2.6.1

springfox-spi-2.6.1

springfox-spring-web-2.6.1

springfox-swagger2-2.6.1

springfox-swagger-common-2.6.1

springfox-swagger-ui-2.6.1

swagger-models-1.5.10

swagger-annotations-1.5.10

spring-plugin-metadata-1.2.0.RELEASE

spring-plugin-core-1.2.0.RELEASE

classmate-1.2.0

guava-18.0

mapstruct-1.0.0.Final

<!-- JSON包 -->

json-lib-2.4-jdk15

json-lib-2.4-sources

<!-- JACKSON包 -->

jackson-annotations 2.6.5

jackson-databind 2.6.5

jackson-core 2.6.5

 

 

 注意事项

        这些jar包的版本不能改变，如果版本改了很可能因为版本的原因而实现不了，说个最简单的Swagger jar包 版本如果变了，很大可能就不行，这个之前博主亲自试验过。

        如果你的项目是maven项目的话，那么给的建议就是将这些jar包配到自己的maven仓库。然后再pom文件里引入，就像我的这样。

 

 

 

 

 

 当然你也可以直接add引入，个人建议还是放在pom里比较规范。

        以上图片是我引入的jar 直接复制就行。

四、代码实现

jar包引入。

        要引入的jar包（第三章）之前就说了。

Config配置

        新建config文件夹,在文件中新建SwaggerConfigFirst.java文件，配置启动相关信息。

 

 然后再配置文件中引入本文件

 

 

 这个SwaggerConFirst类有四个注解，看名称就可以明白是什么意思。其中，@Configuration，@EnableWebMvc和@ComponentScan是Spring的注解，而@EnableSwagger2则是用来启动Swagger支持，表示这是一个Spring Swagger的配置文件。

     之后，定义了一个Bean方法CustomDocket，Spring中名字并不重要，重要的是它返回一个Docket类，DocumentationType.SWAGGER_2作为Docket构造方法的参数，指定了所用的swagger版本2.0，官网上已经在预告3.0版本了。而之后的apiInfo则是调用接下来的apiInfo函数，来创建Docket的信息。apiInfo函数采用ApiInfoBuilder来创建ApiInfo类。

Controller注解

控制层可以有两种方式展现根据大家喜好来。

方式一

 

 方式二

 

 两种方式都可以 看大家喜欢那种写法。

五、成果展现

访问

启动项目 访问地址

        地址是 IP + 端口号 +项目跟路径 + /swagger-ui.html

       我的是http://localhost:8080/springfox_springmvc/swagger-ui.html

后缀是固定的 不要改变

 

 

 

 https://blog.csdn.net/wyb880501/article/details/79576784

https://blog.csdn.net/qq_39082353/article/details/109453310?utm_term=swagger%E9%85%8D%E7%BD%AE%E6%96%87%E4%BB%B6%E8%AF%A6%E8%A7%A3&utm_medium=distribute.pc_aggpage_search_result.none-task-blog-2~all~sobaiduweb~default-0-109453310&spm=3001.4430

https://blog.csdn.net/z591593455/article/details/107091560?utm_term=swagger%E9%85%8D%E7%BD%AE%E6%96%87%E4%BB%B6%E8%AF%A6%E8%A7%A3&utm_medium=distribute.pc_aggpage_search_result.none-task-blog-2~all~sobaiduweb~default-2-107091560&spm=3001.4430