項目開發(fā)中，API 文檔是很重要的一環(huán)，好的API文檔編寫習慣可以是前后端交互時節(jié)約大量時間，當API過多時，寫API文檔無疑是一件費時費力的事，swagger就是一款可以幫助各位快速、優(yōu)雅生成API文檔的一款框架。本文將基于springboot項目集成swagger2框架。

項目結(jié)構(gòu)

2018-12-20-springboot-swagger-項目結(jié)構(gòu)

依賴導入

        <!--swagger2 start-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <!--  bootstrap風格swagger2 ui資源 -->
        <!--
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.8.6</version>
        </dependency>
        -->
        <!--  原生swagger2 ui資源 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>
        <!--swagger2 end-->

Controller層

@RestController
@RequestMapping("/test")
@Api(tags = "測試接口")
public class TestController {

    @PostMapping
    @ApiOperation(value = "post方式接口")
    @ApiResponses(value = {
            @ApiResponse( code = 200 ,message = "success",response = com.ljq.swagger_demo.vo.TestVo.class)
    })
    public TestVo test1(@RequestBody TestVo testVo){
        return testVo;
    }

    @GetMapping
    @ApiOperation(value = "get方式接口")
    @ApiImplicitParams(value = {
            @ApiImplicitParam(name = "name",value = "字符型",paramType = "query",dataType = "String"),
            @ApiImplicitParam(name = "amount",value = "浮點型",paramType = "query",dataType = "Float")
    })
    @ApiResponses(value = {
            @ApiResponse( code = 200 ,message = "success",response = com.ljq.swagger_demo.vo.TestVo.class)
    })
    public TestVo test2(@RequestParam("name")String name,
                        @RequestParam("amount")Float amount){
        return new TestVo(name,amount);
    }
}

Vo層

@Data
@AllArgsConstructor
@NoArgsConstructor
@EqualsAndHashCode(callSuper = false)
@Accessors(chain = true)
@ApiModel(description= "測試實體類")
public class TestVo {

    @ApiModelProperty(value = "字符型")
    private String name;

    @ApiModelProperty(value = "浮點型")
    private Float amount;

}

Config類

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket apiDocket() {

        return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
            .paths(PathSelectors.any())
            .build();
    }

    @Bean
    public UiConfiguration uiConfiguration() {

        return UiConfigurationBuilder.builder()
            .deepLinking(true)
            .defaultModelExpandDepth(1)
            .validatorUrl("")
            .displayOperationId(true)
            .displayRequestDuration(true)
            .tagsSorter(TagsSorter.of("release"))
            .showExtensions(true)
            .build();
    }

    private ApiInfo apiInfo() {

        return new ApiInfoBuilder()
            .title("在線api")
            .description("RESTful API")
            .version("1.0")
            .build();
    }
}

訪問API地址

在瀏覽器輸入ip:端口號/swagger-ui.html

運行效果

2018-12-20-springboot-swagger-運行效果

項目源碼地址

https://github.com/LiJinQ/SwaggerDemo.git

最后推送一下我的個人博客地址
LJQ BLOG