使用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