swagger2.0與spring結合

時間 2019-12-07

標籤 swagger2.0 swagger spring 結合欄目 Spring 简体版

原文原文鏈接

官方文檔：

http://www.baeldung.com/swagger-2-documentation-for-spring-rest-api

swagger是一個先後端api統一文檔和測試框架，注意，不光是一個api文檔，還能夠測試

怎麼使用呢這裏慢慢道來，咱們通常用的都是maven工程，因此這裏直接上maven依賴

<swagger.version>1.5.8</swagger.version>
<io.springfox.version>2.5.0</io.springfox.version>
<!-- swagger start -->
<dependency>
  <groupId>io.swagger</groupId>
  <artifactId>swagger-core</artifactId>
  <version>${swagger.version}</version>
</dependency>
<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger2</artifactId>
  <version>${io.springfox.version}</version>
</dependency>
<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger-ui</artifactId>
  <version>${io.springfox.version}</version>
</dependency>
<!-- swagger end -->

這裏咱們須要注入SwaggerConfiguration配置，直接上代碼

/**
 * Created by max on 8/16/16.
 *
 */
@EnableSwagger2
public class SwaggerConfiguration {

    @Bean
    public Docket getApiInfo() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("outer api")
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build()
                .apiInfo(outApiInfo());

    }

    private ApiInfo outApiInfo() {
        return new ApiInfo(
                "mylearn 先後端接口-外部", // title 標題
                "外部接口文檔", // description 描述 標題下
                "1.0.0", // version
                "http://mylearn/*", // termsOfService
                new Contact("xieyuebin","","xieyuebin@meituan.com"), // contact
                "Apache 2.0", // licence
                "http://www.apache.org/licenses/LICENSE-2.0.html" // licence url
        );

    }

    @Bean
    public UiConfiguration getUiConfig() {
        return new UiConfiguration(
                null,// url,暫不用
                "none",       // docExpansion          => none | list
                "alpha",      // apiSorter             => alpha
                "schema",     // defaultModelRendering => schema
                UiConfiguration.Constants.DEFAULT_SUBMIT_METHODS,
                false,        // enableJsonEditor      => true | false
                true);        // showRequestHeaders    => true | false
    }

這是對於文檔的說明以及ui的一些配置

而後咱們還須要把swagger和spring mvc結合起來，首先在web.xml里加入swagger文檔的訪問路徑：

<!-- swagger ui 的靜態資源交由default處理-->
    <servlet-mapping>
        <servlet-name>default</servlet-name>
        <url-pattern>/swagger-ui.html</url-pattern>
    </servlet-mapping>

而後咱們在dispatch-servlet.xml里加入對swagger靜態資源jar包的訪問路徑以下：

<!-- swagger 配置 ,線上版本須要註釋掉 -->
    <beans:bean class="com.meituan.maxtse.mylearn.swagger.SwaggerConfiguration"/>
    <!-- swagger ui resources-->
    <mvc:resources mapping="/webjars/**" location="classpath:/META-INF/resources/webjars"/>

這裏咱們用到了咱們前面定義的SwaggerConfiguration類

而後咱們在controller和請求參數和返回參數里加入swagger提供的註解，直接上例子

入參：

/**
 * Created by max on 10/11/16.
 */
@ApiModel(description = "用戶請求表單")
public class UserForm {

    @ApiModelProperty(value = "姓名", example = "maxTse",position = 1)
    private String username;

    public String getUsername() {
        return username;
    }

    public void setUsername(String username) {
        this.username = username;
    }

    @Override
    public String toString() {
        return "UserForm{" +
                "username='" + username + '\'' +
                '}';
    }
}

返回值：

@JsonInclude(JsonInclude.Include.NON_NULL)
@ApiModel
public class OutResult<T> implements Serializable {

    @ApiModelProperty(value = "數據", example = "")
    public T data;

    @ApiModelProperty(value = "狀態碼,0表示成功 其餘表示失敗", example = "0")
    public int status;

    @ApiModelProperty(value = "錯誤信息", example = "操做成功")
    public String message = "";

controller：

/**
 * Created by max on 8/16/16.
 */
@Controller
@RequestMapping(value = "/test", consumes = "application/json", produces = "application/json")
public class TestController {

    private static final Logger LOGGER = LoggerFactory.getLogger(TestController.class);

    @ApiOperation(value = "swagger test", notes = "swagger test first", tags = {SwaggerConstants.TEST_TAG})
    @ResponseBody
    @RequestMapping(value = "/first", method = RequestMethod.POST)
    public OutResult<String> first(@RequestBody UserForm userForm) {
        LOGGER.info("first userForm={}", userForm);
        throw new RuntimeException("dd");
/*
        return OutResult.successResult(userForm.getUsername());
*/
    }