springboot 整合 swagger 接口文档

优缺点：

    优点：省去额外的工作量 单独去维护一套接口文档、配置简单（仅使用几个注解即可完成接口文档的编写）、支持在线测试

    缺点：额外的工作量（对于程序员来说）

>>step one：新增依赖

<dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.8.0</version>
        </dependency>

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.8.0</version>
        </dependency>

>>step two：controller 添加注解

@Api(tags = "基础兑换币 相关接口")
@RestController
@RequestMapping(value = "/web-api/v1/base/pair", produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
public class BasePairController {

    @Autowired
    private BasePairService basePairService;

    //分页列表
    @ApiOperation(value = "基础兑换币 列表", notes = "根据交易所ID获取 基础兑换币。")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "market_id", value = "交易所ID | Long", required = true, paramType = "query", defaultValue = "4")
    })
    @RequestMapping(value = "list", method = RequestMethod.GET, produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
    public CommandResult<List<BasePairVO>> listByMarketId(@RequestParam(value = "market_id", defaultValue = "0") Long marketId) {
        if (marketId == 0){
            return CommandResult.ofFail("参数：交易所ID 为空");
        }
        try {
            return basePairService.listByMarketId(marketId);
        }catch (Exception e){
            log.error("【获取 基础兑换币 列表】请求异常", e);
            return CommandResult.ofFail("请求异常");
        }
    }

}

说明：

@Api：使用在 controller上，表明该控制器的作用（用来做什么）

@ApiOperation：使用在具体的方法上，表明该方法的作用（用来做什么）

@ApiImplicitParams：多参数说明

@ApiImplicitParam：单参数说明

>>step three:返回的对象添加注解

@ApiModel(description = "交易所下基础兑换币 列表信息")
@Data
@AllArgsConstructor
@NoArgsConstructor
@JsonIgnoreProperties(ignoreUnknown = true)
public class BasePairVO {

    @ApiModelProperty(value = "基础兑换币ID", position = 1)
    @JsonProperty("base_pair_id")
    private Long basePairId;

    @ApiModelProperty(value = "交易所ID", position = 2)
    @JsonProperty("market_id")
    private Long marketId;

    @ApiModelProperty(value = "交易所的基础兑换币", position = 3)
    @JsonProperty("pair_name")
    private String pairName;

    public static BasePairVO doToVo(TBasePairDO pairDO){
        if (pairDO == null){
            return null;
        }
        return new BasePairVO(pairDO.getAutoId(), pairDO.getMarketId(), pairDO.getPairName().toUpperCase());
    }
}

说明：

@ApiModel：用在返回对象上。

@ApiModelProperty：对返回对象的描述。

 

>>step four: 加配置

@Configuration
public class Swagger2DevConfig {

    @Profile({"default", "pro"})
    @Bean
    public Docket createWebApi() {
        return new Docket(DocumentationType.SWAGGER_2)
            .enable(false)
            .select().build();
    }

    @Profile("dev")
    @Bean
    public Docket createWebApiDev() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfoDev())
                .select()
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                .paths(PathSelectors.any())
                .build();
    }

    @Profile("test")
    @Bean
    public Docket createWebApiTest() {
        return new Docket(DocumentationType.SWAGGER_2)
                .host("test.echo.com/demo")
                .protocols(Sets.newHashSet("https"))
                .apiInfo(apiInfoDev())
                .select()
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfoDev() {
        return new ApiInfoBuilder()
                .title("市值API")
                .description("市值api接口文档\n" +
                        "\n" +
                        "测试环境:https://test.echo.com/demo\n" +
                        "生产环境\thttps://test.echo.com/demo\n")
                .contact(new Contact("echo", "", ""))
                .version("1.0")
                .build();
    }

}

 

>>结束：查看具体效果（https://test.echo.com/demo/swagger-ui.html）