springboot集成swagger

時間 2020-01-29

原文原文鏈接

springboot集成swagger

一、爲何須要swagger

開發人員頻繁的修改服務端的rest接口，而對接人員和測試人員未能在第一時間獲取到最新的文檔

接口編寫完成，須要再花必定的時間去按照模板編寫接口文檔費事費力，不如編寫代碼來的輕鬆

若是你也有同感，那麼swagger絕對是你的救星

二、swagger是什麼

swagger是一個基於註解生成在線api文檔的工具包。有了它編寫好代碼，接口的入參、出參、方法定義上打上指定的註解，輔以描述，那麼框架會根據規範生成格式規範的api在線文檔，與代碼自動保持同步，所見即所得。

一個在線的postman,大部分參數爲你格式化好了，你只需把形參替換成實參就能夠發送請求了

支持導出markdown、pdf、word等第三方格式的文檔

自動標識最新的api,改動一目瞭然

三、如何集成

a、引入pom

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

        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.8.7</version>
        </dependency>

須要說明的是這裏採用的是第三方的swagger-ui，相較於官網的版本，界面更優美，體驗更好。ui只是一個插件，能夠無縫替換

b、代碼上增長註解

入參
@Data
@ApiModel("建立流程文檔")
public class AddDocModel extends ToString {
    @ApiModelProperty("文檔的名稱")
    @NotBlank(message = "name不能爲空")
    private String name;

    @ApiModelProperty("文件的fileKey")
    @NotBlank(message = "fileKey不能爲空")
    private String fileKey;

    @ApiModelProperty("文件id")
    @NotBlank(message = "fileId不能爲空")
    private String fileId;

    @ApiModelProperty("是否加密")
    private Integer encryption;
}

出參
@ApiModel("建立文檔的結果集")
@Data
public class AddDocResult extends BaseResult {
    @ApiModelProperty("文檔id")
    private String docId;
}

方法
@Api(tags = "文檔管理", description = "文檔管理")
public class DocServiceImpl implements DocService {
 @ApiOperation(value = "建立文檔", httpMethod = "POST")
    public AddDocResult addDoc(@RequestBody AddDocModel addDocModel) {
        //接口實現
    }
}

重要註解說明html

ApiModel 用來定義接口的出參和入參的實體類git

ApiModelProperty 定義實體類的屬性值程序員

Api 用來定義api功能模塊github

ApiOperation 定義一個具體的apiweb

httpMethod = "POST" 接口只生成POST請求的文檔spring

@RequestBody 入參採用jsonjson

c、配置swagger

@Configuration
@EnableSwagger2
public class SwaggerConfiguration extends WebMvcConfigurerAdapter {
    private final String SWAGGER_SCAN_BASE_PACKAGE = "top.zhuofan.datafly";

    /**
     * 項目裏的靜態資源路徑指向以下
     *
     * @param registry
     */
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
        super.addResourceHandlers(registry);
    }

    @Override
    public void configureDefaultServletHandling(DefaultServletHandlerConfigurer configurer) {
        configurer.enable();
    }


    @Bean
    public Docket createRestApi() {

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage(SWAGGER_SCAN_BASE_PACKAGE))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {

        return new ApiInfoBuilder()
                .title("卓帆網")
                .description("datafly online doc")
                .termsOfServiceUrl("https://www.chenzhuofan.top/")
                .contact(new Contact("", "", "308679291@qq.com"))
                .version("1.0")
                .build();
    }
}