Swagger API

基于SpringBoot 2.1.6.RELEASE版本

1、依赖包

 <!-- swagger start -->
       <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>

2、Swagger配置类

package com.example.ldap.config;

import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Configurable;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Profile;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.time.LocalDate;
import java.time.LocalDateTime;
import java.util.ArrayList;
import java.util.List;

/**
 * @author lichunlan
 * @description swagger的配置类
 * @since 2020-02-17
 * @Profile({"dev","test"})
 */
@Configurable

public class SwaggerConfig {
    /**
     * 可以注入多个doket，也就是多个版本的api，可以在看到有三个版本groupName不能是重复的，v1和v2是ant风格匹配，配置文件
     * @return
     */
    @Bean
    public Docket api() {
        //可以添加多个header或参数
        ParameterBuilder aParameterBuilder = new ParameterBuilder();
        aParameterBuilder
                .parameterType("header")
                .name("Authorization")
                .description("header中Authorization字段用于认证")
                .modelRef(new ModelRef("string"))
                //非必需，这里是全局配置，然而在登陆的时候是不用验证的
                .required(false).build();
        List<Parameter> aParameters = new ArrayList<Parameter>();
        aParameters.add(aParameterBuilder.build());
        return new Docket(DocumentationType.SWAGGER_2).groupName("v1")
                .directModelSubstitute(LocalDateTime.class, String.class)
                .directModelSubstitute(LocalDate.class, String.class)
                .select()
//                .apis(RequestHandlerSelectors.basePackage("com.example.ldap,controller"))
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.ant("/**")).build().apiInfo(apiInfo()).globalOperationParameters(aParameters);
    }


    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Server端 APIs")
                .version("v0.01")
                .build();
    }
}

3、遇到的问题

• 启动报错

Description:

Parameter 0 of method linkDiscoverers in org.springframework.hateoas.config.HateoasConfiguration required a single bean, but 3 were found:
    - relProviderPluginRegistry: defined by method 'relProviderPluginRegistry' in class path resource [org/springframework/hateoas/config/HateoasConfiguration.class]
    - linkDiscovererRegistry: defined in null
    - entityLinksPluginRegistry: defined by method 'entityLinksPluginRegistry' in class path resource [org/springframework/hateoas/config/WebMvcEntityLinksConfiguration.class]

SpringBoot的版本和Swagger的版本问题
我的SpringBoot 2.1.6.RELEASE Swagger是2.2.2，把Swagger的版本换成2.9,.2就能启动起来了

• 提示Unable to infer base url.

  
  unable to infer base url.png
  

  在application启动类中未定义@EnableSwagger2注解，将@EnableSwagger2从SwaggerConfig类中移动到application启动类即可

4、Swagger文档

启动SpringBoot项目，访问 http://localhost:9999/swagger-ui.html

swagger.png zhujie.png

前端就能清晰的知道接口名、请求方法、输入参数和返回的信息是哪些，字段的意义，后端只要一更新，前端就能立即呈现修改的结果

5、Swagger常用注解以及具体使用方法

swagger通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等。

• @Api：修饰整个类，描述Controller的作用

  
  api.png

• @ApiOperation：描述一个类的一个方法，或者说一个接口

  
  apiOperation.png

• @ApiParam：单个参数描述

  
  apiParam.png

• @ApiModel：用对象来接收参数

  
  apiModel.png

• @ApiModelProperty：用对象接收参数时，描述对象的一个字段

  
  apiModelProperty.png

• @ApiIgnore：使用该注解忽略这个API

  
  apiIgnore.png

• @ApiImplicitParam：一个请求参数

• @ApiImplicitParams：多个请求参数

  
  apiImplicitParams&apiImplicitParam.png

@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiError ：发生错误返回的信息