使用Swagger给项目添加在线文档

1.Swagger的作用:

呈现您的 API 规范并与您的 API 进行交互，同时可以对其进行定义,修改了什么对应的文档也会发送改变,可以通过Swagger把SpringMvc对外的接口通过注解的方式添加到SwaggerUI中

对之前的项目添加swagger文档界面UI,可以直接通过UI发送对应接口的请求,这样以后项目可以通过接口和其他程序交互,这样对方的技术就知道怎么对接,本质上就是开发接口

2.添加Swagger坐标

对pom.xml中添加Swagger的maven坐标

         <!--swagger-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

3.创建Swagger的配置类

创建SwaggerConfig类用来配置Swagger

@EnableSwagger2//开启swagger2
@Configuration//配置类:@Configuation注解包含了@Component注解
public class SwaggerConfig{

    @Bean
    public Docket creatRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())//创建一个ApiInfo对象里面添加一些文档页面内容
                .select()
                //控制暴露出去的路径下的实例
                //如果某个接口不想暴露,可以使用以下注解
                //@ApiIgnore 这样,该接口就不会暴露在 swagger2 的页面下
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("Itmei对接文档")//页面标题
                .contact("Itmei创建")//创建人
                .version("1.0")//文档版本号
                .description("API 描述 :</br>\n\r" +
                        "&nbsp;一、有赞对接： </br>\n\r" +
                        "&nbsp;二、上传文件： <br />\n\r"
                        )//描述信息
                .build();
    }
}

在配置一个WebMvcConfig因为测试的时候出现问题添加这个类后解决了

@Configuration
public class WebMvcConfig extends WebMvcConfigurationSupport {

    /**
     * 发现如果继承了WebMvcConfigurationSupport，则在yml中配置的相关内容会失效。 需要重新指定静态资源
     *
     * @param registry
     */
    @Override
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

未添加该类报错:documentationPluginsBootstrapper空指针异常

Failed to start bean ‘documentationPluginsBootstrapper’; nested exception is java.lang.NullPointerException

4.配置Controller类

对一个post请求类型的接口进行设置:

@Api(value = “youzan”,description = “有赞接口”)//添加需要展示在swagger上的类
@ApiOperation(value = “code换token”)//描述一个类的一个方法，或者说一个接口
@ApiImplicitParams({
                @ApiImplicitParam(name=“code”,paramType=“query”,dataType = “String”,required=true,value=“有赞Code”)//一个请求参数
})//多个请求参数
@ApiResponses({
                @ApiResponse(code=400,message=“请求参数没填好”),//描述Http的响应类型
                @ApiResponse(code=401,message=“请求权限不足”),
                @ApiResponse(code=404,message=“请求路径没有或页面跳转路径不对”),
                @ApiResponse(code=503,message=“目前无法使用服务器”)
})//Http响应整体描述

swagger页面的效果

需要注意的是请求的接口不要使用@RequestMapping要不然定义请求的方法
如

如果是单独@RequestMapping和请求路径你就会得到这么多的请求类型

指定好请求类型后

里面的参数解析,关于请求的模板来源于我们响应返回的类型

paramType：表示参数放在哪个地方
header–>请求参数的获取：@RequestHeader(代码中接收注解)
query–>请求参数的获取：@RequestParam(代码中接收注解)
path（用于restful接口）–>请求参数的获取：@PathVariable(代码中接收注解)
body–>请求参数的获取：@RequestBody(代码中接收注解)
form（不常用）

实体类的内容是和swagger响应成功的参数是一致的

我们现在可以直接通过Swagger页面进行请求调用后端接口

现在我们接口都是比较简单的传递的类型都是简单的类型,我们现在写一个接口由于传递对象信息
写一个保存商品信息的接口,通过传递用户标识和商品信息用来保存商品!

注意:

需要注意的是dataType = "GoodsInfoPojo"参数中的GoodsInfoPojo值的由来是我们在实体类中添加了@ApiModel注解的value定义了名称,所以dataType的值就必须一样

2.contrllor接收对象json必须添加@RequestBody 注解才能被解析成一个对象,@ApiImplicitParam的name值是需要和接收的传参要一致

查看swagger可以看出goodsInfo参数需要传递的实体类参数

点击这个model

会展示实体类的类型,我们还可以对这些属性进行解释

在实体类接口的参数名称添加注解@ApiModelProperty(value = "商品名称",required = true)

在看文档就会显示带*那些需要必递,还有属性的作用

而且我swagger我们使用的版本比较高所以界面会有所不同

Models里面就是我们接口的请求实体类型和响应实体类展示

发现一个有趣的事情关于响应的对象我们没有在实体类UserInfo添加@ApiModel也可以被展示出来

我们有在属性名称上添加@ApiModelProperty这样swagger也会展示出来我们定义的介绍,默认情况下如果请求的和响应参数的名称都是实体类名称可以不添加该注解
如图:
实体类注释掉

接口上

重新运行代码:

还是可以展示出来

5.swagger文件上传改造

使用到新注解@ApiParam:作用在方法里面
解释:用在@RequestParam的前面，定义swagger请求的参数形式

@ApiParam与@ApiImplicitParams的区别

本质上:功能是相同的,但是@ApiParam接口中说到需要在JAX-RS 1.x2.x
注释结合才能使用,而@ApiImplicitParams没有这个限制
@ApiImplicitParams:用在请求的方法上，表示一组参数说明
@ApiImplicitParam:在@ApiImplicitParams注解中，指定一个请求参数的各个方面
JAX-RS:即Java API for RESTful Web Services