使用swagger生成API说明文档

 

项目地址点这里

一、构建spring-boot项目简单介绍

自己没有项目可以测试时，先在本地搭建一个spring-boot项目去验证swagger生成API说明文档的流程，构建spring-boot项目有三种方式，可以参考官方文档：https://spring.io/guides/gs/spring-boot/#use-maven
我这里使用的是maven构建方式，需要导入的包有：

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.0.5.RELEASE</version>
    </parent>
    
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
    </dependencies>
    <properties>
        <java.version>1.8</java.version>
    </properties>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>

然后编写部分代码，确保项目可以正常启动。项目构建就说这么一点吧，后面开始介绍如何使用swagger生成API文档。

二、使用swagger生成API文档

1、导入maven依赖

        <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、在项目目录下编写SwaggerConfig类

package com.test.swagger;

import com.google.common.base.Predicate;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.autoconfigure.condition.ConditionalOnExpression;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import static com.google.common.base.Predicates.or;
import static springfox.documentation.builders.PathSelectors.regex;

@Configuration
@EnableSwagger2
@ConditionalOnExpression("${swagger.enable:true}")
@ComponentScan(basePackages = {"com.test.swagger.controller"})
@SpringBootApplication
public class SwaggerConfig {

    public static void main(String[] args) {
        SpringApplication.run(SwaggerConfig.class, args);
    }
    
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(paths())
                .build()
                .useDefaultResponseMessages(false);
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("《--Swagger生成API文档演示案例--》")//标题
                .termsOfServiceUrl("")
                .description("演示API文档生成的过程")//描述
                .version("1.0.0")//版本号
                .build();
    }

    //可以匹配满足下面条件的任何一个表达式
    private Predicate<String> paths() {
        return or(
                regex("/api/.*"),
                regex("/some.*"),
                regex("/contacts.*"),
                regex("/pet.*"),
                regex("/springsRestController.*"),
                regex("/test.*"));
    }
}

3、TestController代码

package com.test.swagger.controller;
import com.test.swagger.bean.TestRequest;
import com.test.swagger.bean.TestResult;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/test")
@Api(value = "TestController", description = " Test api", tags = "Test控制器")
public class TestController {

    @ApiOperation(value = "测试POST请求", notes = "测试方法")
    @RequestMapping(value = "/postAsBody", method = RequestMethod.POST)
    public TestResult testPostAsBody(@RequestBody TestRequest testRequest) {
        TestResult result = new TestResult();
        result.setParam1(testRequest.getParam1());
        result.setParam2(testRequest.getParam2());
        return result;
    }

    @ApiOperation(value = "测试POST请求(form)", notes = "测试方法")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "param1", value = "第一个参数", required = true, paramType = "form"),
            @ApiImplicitParam(name = "param2", value = "第二个参数", required = true, paramType = "form"),
    })
    @RequestMapping(value = "/postAsForm", method = RequestMethod.POST)
    public TestResult testPostAsForm(String param1,String param2) {
        TestResult result = new TestResult();
        result.setParam1(param1);
        result.setParam2(param2);
        return result;
    }

    @ApiOperation(value = "测试GET请求", notes = "测试方法")
    @RequestMapping(value = "/get", method = RequestMethod.GET)
    public String testGet() {
        return "**测试**";
    }
}

4、本地访问

项目启动后访问 http://localhost:8080/swagger-ui.html#/ 就可以查看简单的API文档了

先研究这么多，更多Swagger的相关注解说明，直接参考官方文档：
Springfox Reference Documentation